Skip to content

Contribution Workflow

Scope and Goals

This contribution workflow defines how changes are proposed, implemented, reviewed, and merged.

Its goals are to: - ensure traceability between issues and code changes - improve review quality through clear context - reduce the risk of unsafe or undocumented behavior changes - keep the contribution process predictable and transparent

This workflow applies to all code and documentation contributions unless explicitly stated otherwise.

Contribution Workflow Overview

graph TD
    A[Idea / Change] --> B{Contribution Type?}

    B -- Lightweight --> C[Create Merge Request]
    C --> D[Implement Change]
    D --> E[Review & Merge]

    B -- Standard --> F{Existing Issue?}
    F -- Yes --> G[Use Existing Issue]
    F -- No --> H[Create Issue]

    G --> I[Create MR from Issue]
    H --> I
    I --> J[Draft MR]
    J --> K[Implement Change]
    K --> L[Update README.md and /docs if needed]
    L --> M[CI Passes]
    M --> N[Remove Draft]
    N --> E

Contribution Types

To balance transparency with contributor convenience, we distinguish between two types of contributions.

Standard Contributions (Issue Required)

An issue must exist before starting work if a change: - affects hardware behavior - modifies system or control logic - impacts safety mechanisms - changes public interfaces or APIs

Lightweight Contributions (Issue Optional)

An issue is optional for: - documentation-only changes - typo fixes - comment-only changes - non-functional refactoring without behavioral impact

Rule of thumb: If you are unsure whether your change is standard or lightweight, assume it is a standard contribution and create an issue first.

Issue-Driven Development (Standard Contributions)

For standard contributions, development must be tracked via an issue.

  1. Search for an existing issue.
  2. Create a new issue if none exists.
  3. Create a Merge Request from the issue using GitLab’s interface.
  4. This creates a linked branch automatically.
  5. Keep the Merge Request in draft state while work is ongoing.
  6. Remove the draft status once the change is complete and ready for review.

Coding Standards

  • Standard C++ formatting is required
  • All public methods must include Doxygen-style comments

Documentation Requirements

Changes that affect system behavior or hardware interaction must update the corresponding documentation within the same Merge Request. All documentation must follow the Documentation Standards.

You can preview your documentation locally. For details please expand this section.

It is possible to build the documentation of a repo locally. For this purpose you need python installed.

  • Download, copy, and paste the zensical.toml configuration file from the Documentation Hub repo into your locally checked out repo.

  • (Optional) Create a virtual environment and activate it

    python -m venv .venv
.venv\Scripts\activate

    python -m venv .venv
source .venv/bin/activate

    python -m venv .venv
source .venv/bin/activate

  • Install zensical

    pip install zensical

  • Build the documentation

    zensical serve

  • The documentation can then be previewed under http://localhost:8000.

Warning

Be carefull not to commit and push the zensical.toml or any generated files from the public directory.

Safety Requirements

This project controls physical hardware and heavy machinery. Any change that affects control loops, safety logic, or hardware interaction must include evidence of appropriate testing or validation. This may include:

  • Simulation results (for algorithm or control logic changes)
  • Hardware test logs or videos (for direct hardware interaction changes)
  • Code review and analysis documentation (for safety-critical logic)
  • Integration test results (for system behavior changes)

Reference this evidence in the Merge Request description so reviewers can assess the safety implications of your change.

Merge Request Checklist

Before requesting review, ensure that:

  • CI/CD pipeline passes (if applicable)
  • README.md and Documentation in /docs is updated (if applicable)
  • Branch is rebased on the latest main
  • Merge Request is no longer marked as draft
  • Safety-related changes have been tested in simulation

Review and Merge Process

Once a Merge Request is marked as ready for review:

  1. A maintainer reviews the change for:
  2. correctness
  3. safety implications
  4. documentation completeness
  5. adherence to coding standards
  6. Feedback is provided directly in the Merge Request.
  7. The contributor addresses review comments and updates the branch as needed.
  8. After approval, a maintainer merges the Merge Request.

We aim to provide an initial review within 48 hours, depending on availability.