Git Workflow

SPECTRE uses a GitLab merge request-based workflow. All contributions go through a branch and merge request cycle — direct commits to main are not allowed.

Overview

The typical contribution cycle is:

  1. Open or pick up a GitLab issue

  2. Create a branch

  3. Make commits

  4. Open a Merge Request

  5. Pass code review and CI

  6. Merge

Open or pick up a GitLab issue

Every non-trivial contribution should be tied to a GitLab issue. Issues are used to track bugs, feature requests, and planned work. Before starting, check whether an issue already exists for the work you intend to do. If not, open one and describe the problem or feature clearly.

Create a branch

If you are working from a GitLab issue, the recommended approach is to create a draft merge request directly from the issue page. GitLab will automatically create a branch tied to that issue and open a draft MR. The draft MR acts as a discussion forum for the work-in-progress: you can post questions, share early results, and receive feedback before the implementation is complete. Mark the MR as ready for review only when the work is done.

Alternatively, create a branch manually from an up-to-date main:

git switch main
git pull origin main
git switch -c my-descriptive-branch-name

Use a short, descriptive branch name that conveys what the branch does (e.g. fix-coordinate-transform or add-vmec-output). There is no strict naming convention, but clarity is preferred.

Note

The no-commit-to-branch pre-commit hook prevents accidental direct commits to main. See Pre-commit Hooks for details.

Make commits

Keep commits small and focused. Each commit should represent one logical change. Write commit messages in the imperative mood and summarize what the commit does and why.

A commit message must start with a short summary line, followed by a blank line, and then a more detailed explanation if needed:

Fix off-by-one error in surface indexing

The loop upper bound was inclusive, causing the last surface to be
processed twice. Changed to exclusive to match the array layout.

Tip

If you cannot summarize a commit in a single line, the commit is probably doing too many things at once. Consider splitting it into smaller, more focused commits.

Open a Merge Request

Push your branch to GitLab and open a Merge Request (MR) targeting main:

git push origin my-descriptive-branch-name

Then go to the GitLab project page and click New merge request. In the MR description:

  • Summarize what the MR does and why.

  • Reference the related issue using the Closes #<issue-number> keyword so GitLab closes it automatically on merge.

  • List any important decisions or trade-offs made during implementation.

Pass code review and CI

Before a MR can be merged:

  • CI must pass. The pipeline runs automated checks including Ruff linting and formatting of the Python code. Ensure your changes do not introduce any linting errors (see Coding Conventions).

  • At least one reviewer must approve. Assign a reviewer in GitLab. Address all review comments before requesting re-review.

Merge

Once the MR is approved and CI is green, the branch can be merged into main. The branch is deleted automatically after merge.