Skip to main content

Project governance & contribution

Welcome to the fluxrig institutional engineering hub. This section defines the governance model, contribution workflows, and licensing boundaries for the project. Our goal is to maintain an open-core ecosystem where architectural integrity, operational safety, and Technical Autonomy are never compromised.

To start contributing, follow the standard build and test cycle:

# Clone & Setup
git clone https://github.com/jaab-tech/fluxrig.git
cd fluxrig

# Build Toolchain (Binaries + Catalog)
make build

# Add to PATH (Optional but Recommended)
export PATH=$PATH:$(pwd)/bin

Local validation loop​

Before submitting a Pull Request, verify your changes using the institutional validation loop:

make lint       # Security & Style check
make test       # Core Logic check
make test-robot # Protocol Integrity check
make regression # System E2E check

Before you open a pull request​

Every pull request must reference an issue. Open the issue first, and describe the problem or the change. For a large change, agree on the approach with a maintainer before you write code. Then create your branch from dev, open the pull request against dev, and put Closes #<issue> in its body.

Community pull requests target dev, not main. Public main holds the release snapshots. Each release rebuilds it from the release tag, and the next snapshot replaces any change merged into main. The maintainers port each accepted change from dev into the next release.

The maintainers close a pull request that has no linked issue, and ask for an issue first.

The reason is simple. The issue holds the discussion and the decision. The pull request holds the code. A reviewer can then check the code against the agreed change, and the history keeps the reason next to the change.

One issue, one change. Split unrelated work into separate issues and pull requests. If your change needs an enterprise gear (sim_source, sim_responder), say so on the issue first. Those gears live in a separate repository, and a pull request here must not depend on them.

The developer journey​

Navigating an orchestration platform requires a clear roadmap. We maintain an institutional four-stage process from induction to production.

Phase: architectural induction​

Start by aligning your local workstation with the Environment & layout guide. You need a "Dual Head" setup (Mixer + Rack) to verify logic end-to-end.

Phase: implementation​

Follow the Developing specialized gears tutorial. Ensure all new code adheres to the Engineering standards. Focus on context propagation, error wrapping, and structured logging.

Phase: verification​

We maintain a "Hard Engineering" posture. Every contribution is a reflection of the system's overall reliability and is not complete until it passes every verification layer:

  • Unit & Integration: make test (Minimum 60% coverage).
  • Protocol Integrity: make test-robot (Real-world signal validation via Robot Framework).
  • System Regression: make regression (Full E2E parity).

Governance & integrity​

Developer Certificate of Origin (DCO)​

To protect the open-source integrity and maintain clear licensing boundaries, fluxrig requires a DCO 1.1 sign-off on every commit. This is a legally binding statement that you have the right to submit the code.

AI code hygiene (Human accountability protocol)​

We embrace AI-assisted engineering but maintain absolute human accountability. We treat AI-generated code as a third-party dependency:

  1. Deterministic Validation: Every AI-assisted contribution must pass functional validation via the full institutional test suite.
  2. Architectural Curation: The human author must ensure AI-generated blocks adhere to the project's Engineering standards and naming conventions (Mixer, Rack, Gear).
  3. Institutional Accountability: The human engineer signing the DCO sign-off takes full responsibility for the code's performance, security, and long-term maintainability.

IMPORTANT

We view AI as an augmentation tool, but the Human Architect remains the final arbiter of what the system does.

Dependency hygiene​

We maintain strict compliance to ensure no "License Contamination":

  • Permissive Linkage: Use only libraries with Apache 2.0, MIT, or BSD-style licenses.
  • AGPL Boundaries: Access external services (e.g., Grafana) solely via network protocols. Never link against AGPL code.

Licensing & commercial strategy​

fluxrig operates under a Loose Open Core model. The boundary is a principle rather than a list, so that it stays legible as the product grows.

  • Foundation (Apache 2.0): It includes the core engine (fluxrig, Rack, Mixer) and every Gear that the project published in the open repository. The commitment is directional: what the project published under Apache 2.0 stays under Apache 2.0, in that version and in the ones that follow. The project never withdraws, relicenses, or moves anything already open behind a paywall later.
  • Commercial: Capability beyond that set. It includes:
    • Operational surfaces such as a visual console, role-based access control and an audit console over the log and registry data (the log persistence itself is in the open engine; the surface over it is here).
    • Long-term analytics.
    • Development and certification tooling.
    • Specialised or licensed protocol dialects.
    • Custom engineering. Some of it sits on the production path and some of it does not, so the line is not "free until the traffic is real". It is simply what is in the open set and what is additional to it.

Today that set is the gears that the project published under the Enterprise offering: sim_source and sim_responder. They use the Business Source License 1.1 in a separate repository from the engine. Each component states its licensing terms on its own page.

Community engagement​

  • Discord: Real-time architectural collaboration.
  • GitHub Issues: Official institutional tracking.
  • Code of conduct: The project bases decisions strictly on technical merit and benchmarked reality.