Git workflow

Forks and Branches

  • Development should take place in a separate fork. The phoenix/parallax repository should be reserved for the up-to-date master branch, as well as branches for release versions.
  • Do not push directly to the master branch in your fork. Instead, keep your fork’s master branch in sync with the phoenix/parallax master branch.
  • Use git rebase to ensure your feature branches stay up to date with the latest changes from the target branch.
  • Always create a new branch for each feature, bug fix, or task. Keep branch names descriptive and relevant to the task at hand. For example use the following prefixes:
  • feat: Feature – a new or modified feature.
  • fix: Bug fix – a fix for an identified issue.
  • junk: Experimental – a temporary branch for experimentation.
  • opt: Optimization – performance improvements with no functional changes.
  • infra: Infrastructure – changes to build, test, or runtime environments (e.g., CMake, submission scripts).
  • refactor: Refactoring – code restructuring with no functional changes.
  • doc: Documentation – updates or additions to documentation with no functional changes.

Commits

  • Commit messages should be clear, concise, and as descriptive as possible, while keeping the message short.
  • Follow the GIT 50/72 format:
  • The first line should be 50 characters or less.
  • After a blank line, wrap the remaining text at 72 characters.
  • Each commit message should be prefixed with one of the following tags to indicate its purpose:
  • [expt]: Experiment – use this for feature branches where you’re experimenting with new ideas or approaches. This acts as a record of development.
  • [fix]: Fix – use this for addressing an issue or problem, particularly related to experimental code.
  • [test]: Test – use this for testing an experimental feature or, preferably, adding unit tests for an experimental feature.
  • [good]: Refined – use this to indicate changes made after testing something experimental, bringing it to a more stable state.
  • [bug]: Bug – use this to mark commits that address a bug. This should include details on how to replicate the issue when checking out the commit.
  • [std]: Standards – use this for commits that make changes to adhere to coding standards, with no functional changes.
  • [post]: Post-processing – use this for changes related to post-processing routines.
  • [doc]: Documentation – use this for changes or additions to documentation, with no functional changes.

Merge Requests

  • Always include a detailed description for your merge request. This should explain the scope of the changes, what has been implemented, and how it works.
  • Attach any supplementary material that might be relevant, such as significant results (e.g., a scaling plot if you’ve made improvements to parallel efficiency).
  • Provide references or links to additional resources or related work, if applicable.
  • Use the WIP: (Work In Progress) or DRAFT: prefix for merge requests that are still under development.
  • Choose an assignee and possibly a reviewer to review your merge request.
  • Both developers and reviewers should complete their tasks in a timely manner. Don’t let merge requests linger or leave them without attention.
  • Before merging the pipeline must pass.

Pipeline

The pipeline tests the integrity of the build with every push and ensures that both unit tests and integration tests pass. For the exact configuration and definitions of these tests we refer to the cicd directory. The pipeline can be executed exclusively via shared runners from MPCDF. Any test in the pipeline can be run with fewer than 4 MPI processes.