Infinito.Nexus Contribution Model

Development
1

Infinito.Nexus follows a strict and scalable contribution model designed for stability, quality assurance, and CI/CD efficiency.

All development must take place in Folks (Forks) — never directly in the main repository.

This document explains the workflow and the reasoning behind it.

1. Create a Fork – Never Work on Main

Before starting any change:

  1. Fork the official Infinito.Nexus repository

:backhand_index_pointing_right: https://github.com/kevinveenbirkenbach/infinito-nexus

  1. Clone your personal fork.

  2. Create a feature branch in your fork.

  3. Implement your changes there.

All development — features, bug fixes, refactoring, documentation, or experiments — must happen inside your forked repository.

Why?

  • Keeps main stable at all times
  • Prevents broken pipelines
  • Enables isolated CI testing
  • Allows experimentation without risk

The main branch is considered production-grade and must remain clean and green.

2. Work Inside Your Folk

Inside your fork:

  • Follow the established repository structure.
  • Respect the canonical role templates and patterns.
  • Follow naming conventions and CI/CD integration standards.
  • Keep commits small and meaningful.
  • Ensure reproducibility.

Before even thinking about a Pull Request:

:check_mark: Run all local tests
:check_mark: Validate linting
:check_mark: Ensure formatting compliance
:check_mark: Confirm CI passes in your fork

Local Checks (Makefile Targets)

The canonical way to run formatting, linting, and tests is via make (from the repository root).

Formatting

make format

Runs shfmt for shell scripts and ruff for Python (format + auto-fixable lint rules).

Linting & Tests (CI-like, inside Docker)

Most code checks run inside the infinito container (Docker Compose profile ci), so start the stack first:

make up

Then run the checks you need:

make test-lint
make test-unit
make test-integration

To run the full suite:

make test

Optional teardown:

make down

Ansible Syntax Check

make lint-ansible

Runs ansible-playbook --syntax-check against playbook.yml.

Deployment Smoke Tests (Optional)

For end-to-end deploy testing against the local development stack, use the test-local-* targets (some are destructive and will purge state). Start here:

  • scripts/tests/deploy/local/README.md

3. CI/CD Must Pass in the Fork First

This is critical.

All CI/CD pipelines in your fork must pass before creating a Pull Request.

Why is this mandatory?

The main repository’s CI/CD runners are shared and limited resources.

If contributors push untested or failing changes directly into PRs, it:

  • Overloads the main action runners
  • Delays other contributors
  • Consumes unnecessary compute resources
  • Reduces overall system reliability

Therefore:

:red_exclamation_mark: If CI fails in your fork, fix it there — do not rely on the main repository to test it for you.

Your fork is your responsibility.

The main repository is not a testing playground.

4. CI/CD Debugging & Resource-Efficient Execution :wrench:

Whenever a CI/CD pipeline fails, you must follow the official debugging workflow:

:backhand_index_pointing_right: https://s.infinito.nexus/debbuging

This guide defines how to:

  • Export and analyze job logs
  • Use AI-assisted debugging
  • Properly handle unrelated failures
  • Create issues when needed

Following this process is mandatory to ensure reproducible and efficient debugging.

:rocket: Running Targeted Manual CI Jobs

To avoid unnecessary load on shared GitHub Action runners, do not repeatedly trigger full CI pipelines.

Instead, use the manual workflow:

:backhand_index_pointing_right: https://github.com/infinito-nexus/core/blob/main/.github/workflows/entry-manual.yml

How to trigger:

  1. Open the GitHub Actions tab
  2. Select “CI (Manual)”
  3. Click “Run workflow”

Then configure:

  • Branch: your working branch
  • Distro: debian
  • App whitelist: name of the affected app (e.g. web-app-openproject)

This executes a focused deployment test, significantly reducing CI overhead.

:light_bulb: Why this matters

  • :high_voltage: Faster feedback cycles
  • :money_with_wings: Reduced CI/CD costs
  • :battery: Less pressure on shared runners
  • :bullseye: More precise debugging

5. Pull Request Requirements

Only create a Pull Request when:

  • Your fork’s CI pipeline is fully green
  • The branch is rebased on current main
  • Changes are documented
  • Commit history is clean

A Pull Request should:

  • Be small and focused
  • Explain the purpose clearly
  • Reference related issues if applicable
  • Follow semantic structure

6. Why This Model Matters

Infinito.Nexus is designed to scale.

Without a strict fork-based workflow:

  • CI/CD becomes unstable
  • Review overhead increases
  • Regression risk rises
  • The project velocity drops

By enforcing:

  • Fork-first development
  • Green CI in fork
  • Clean PR submission

we ensure:

  • Stable main
  • Efficient resource usage
  • High-quality merges
  • Predictable delivery cycles

7. Summary

Golden Rule:

Work in your Folk.
Pass CI in your Folk.
Then open a Pull Request.

No direct commits to main.
No CI failures in PR.
No shortcuts.

This keeps Infinito.Nexus robust, scalable, and sustainable :rocket: