Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ShipSoft/FairShip/llms.txt

Use this file to discover all available pages before exploring further.

FairShip welcomes any and all contributions — whether you are fixing a typo, adding a detector module, or refactoring a legacy algorithm. Pull requests are the preferred mechanism because they let the team review, discuss, and iterate before merging, but if you need help navigating Git you are always welcome to reach out directly. The single most important habit to build is writing small, self-contained commits: each commit should introduce one logical change that can be read, understood, and reverted independently. This discipline keeps review tractable for a volunteer collaboration spread across many institutes.

​
Branch Overview

FairShip maintains several long-lived branches with distinct purposes:

master

Main development branch. All Python code must be Python 3. This is where new features and fixes targeting the current SHiP detector design land. Requires aliBuild default release.

charmdet

Branch for the charm cross-section measurement. Kept as a reference for potential future studies.

SHiP-2018

Frozen branch for the CDS, kept for backward compatibility. Python 2 only. Requires aliBuild default fairship-2018. Do not open new feature PRs against this branch.

muflux

Branch for the muon flux analysis. Python 2 only. Requires aliBuild default fairship-2018.
The SHiP-2018 and muflux branches are effectively frozen. Target master for all new development unless you are specifically working on the charm or muon flux programmes.

​
Contribution Workflow

1

Read the SHiP Git Tutorial

Even if you are an experienced Git user, read the SHiP Git Tutorial first. It explains the collaboration’s conventions for forks, branches, commit messages, and pull request etiquette.
2

Fork and clone

Fork the repository on GitHub, then clone your fork locally:
git clone https://github.com/<your-username>/FairShip.git
cd FairShip
Because FairShip uses git-lfs for large binary files (field maps, etc.), initialise LFS if you have not done so before:
git lfs install
3

Create a feature branch

Branch off master (or the appropriate long-lived branch) with a descriptive name:
git checkout master
git pull upstream master
git checkout -b feature/my-descriptive-change
4

Install pre-commit hooks

Pre-commit hooks enforce style and catch common mistakes automatically on every git commit. Install them once after cloning:
pixi run pre-commit install
# or, if pre-commit is available in your PATH:
pre-commit install
The hooks run clang-format, ruff, cpplint, codespell, REUSE validation, and more. See the Pre-commit Hooks section below for the full list.
5

Write small, reviewable commits

Commit one logical change at a time. A good commit message has a short imperative subject line and, where helpful, a body explaining why the change is made:
feat(muon-shield): add TRY_2025 geometry option

The TRY_2025 shield variant is used as the default in CI.
Adds a new entry to the shield name registry and updates
the geometry configuration loader accordingly.
6

Run static analysis before pushing

Use the pixi tasks to catch C++ and Python issues before CI sees them:
# C++ — pass the files you changed
CPP_FILES="passive/ShipMuonShield.cxx" pixi run ci-clang-tidy

# Python — pass the files you changed
PY_FILES="python/hnl.py" pixi run ci-pyrefly
7

Open a pull request

Push your branch to your fork and open a PR against master. Fill in the description with context for reviewers: what problem is solved, how it is tested, and any caveats. GitHub will automatically request review from the relevant code owners (see CODEOWNERS).

​
Code Style

FairShip targets modern, readable C++ and enforces style automatically through three tools, all of which run as pre-commit hooks and in CI.clang-format reformats code to the Google C++ style. The configuration lives in .clang-format at the repository root:
---
Language: Cpp
BasedOnStyle: Google
You can apply it manually:
clang-format -i path/to/MyFile.cxx
cpplint checks for Google C++ style guide violations. FairShip customises a subset of rules in CPPLINT.cfg — whitespace, legal headers, several readability and runtime checks, and auto-generated dictionary files are excluded:
set noparent
linelength=100
filter=-whitespace
filter=-legal
filter=-readability/nolint
filter=-readability/braces
filter=-readability/fn_size
filter=-readability/namespace
filter=-readability/todo
filter=-readability/multiline_string
filter=-runtime/arrays
filter=-runtime/printf
filter=-build/include_order
filter=-build/include_subdir
filter=-build/include_what_you_use
filter=-build/namespaces
exclude_files=G__*Dict.cxx
clang-tidy performs deeper static analysis. Run it via pixi, passing files through the CPP_FILES environment variable:
CPP_FILES="strawtubes/StrawTubes.cxx" pixi run ci-clang-tidy
The full set of C++ conventions — including naming, header organisation, and ROOT/FairRoot idioms — is documented in the C++ guidelines wiki page.
All Python code in FairShip targets Python 3.12. Two tools enforce style and correctness.ruff is the linter and formatter, configured in pyproject.toml:
[tool.ruff]
line-length = 120
target-version = "py312"

[tool.ruff.lint]
select = ["B", "C4", "E", "F", "I", "RUF", "SIM", "UP", "W"]
The enabled rule sets cover bugbear (B), comprehensions (C4), pycodestyle errors and warnings (E, W), pyflakes (F), import sorting (I), Ruff-specific rules (RUF), simplification (SIM), and pyupgrade modernisation (UP). A number of rules are intentionally disabled for physics code (Greek Unicode, %-formatting, manual loop counters, etc.) — see pyproject.toml for the full ignore list.Run ruff directly:
ruff check --fix python/hnl.py
ruff format python/hnl.py
pyrefly is the type checker, also configured in pyproject.toml. It targets Python 3.12 and searches python/ and stubs/ for type information:
PY_FILES="python/hnl.py" pixi run ci-pyrefly
The full Python style and documentation conventions are covered in the Python guidelines wiki page.

​
Pre-commit Hooks

FairShip uses pre-commit to enforce style and correctness automatically. After running pre-commit install, each git commit runs the following hooks:
HookPurpose
trailing-whitespaceRemoves trailing whitespace (excluding .dat files)
end-of-file-fixerEnsures files end with a newline
check-yaml, check-tomlValidates YAML and TOML syntax
check-added-large-filesWarns when large files are committed without LFS
check-astValidates Python AST
check-merge-conflictDetects unresolved merge conflict markers
check-vcs-permalinksEnsures VCS links point to specific commits, not mutable refs
check-executables-have-shebangsEnsures executable files have shebang lines
mixed-line-endingNormalises line endings
ruff-check + ruff-formatPython linting and formatting
clang-formatC++ formatting (excludes LinkDef.h)
cpplintC++ style checking (excludes LinkDef.h)
codespellSpell-checking across all text files
pyupgradeUpgrades Python syntax to 3.12+ idioms
mypyType-checking for a curated set of Python modules
validate-cffValidates the CITATION.cff file
reuseChecks REUSE licensing compliance
gersemiFormats CMake files
yamlfmtFormats YAML files
The pre-commit.ci service runs these checks automatically on every pull request. You can see the latest status at results.pre-commit.ci. Passing hooks locally before pushing saves a CI round-trip.

​
Versioning and Changelog

FairShip uses Calendar Versioning in year.month format, with the option of a patch component (year.month.patch) for hotfixes. The CHANGELOG.md at the repository root records all notable changes following the Keep a Changelog format. When contributing a user-visible change, add an entry to the ## Unreleased section of CHANGELOG.md under the appropriate heading (Added, Changed, Fixed, or Removed).

​
License and REUSE Compliance

FairShip is distributed under LGPL-3.0-or-later. Copyright is held by CERN for the benefit of the SHiP Collaboration. Some components carry different licences — check individual file headers and the LICENSES/ directory. The project follows the REUSE specification, which means every source file must carry an SPDX licence expression and copyright notice (either inline or via a corresponding .license sidecar file). The reuse pre-commit hook enforces this. If you add new files, include the appropriate header: 
// SPDX-FileCopyrightText: <year> CERN for the benefit of the SHiP Collaboration
// SPDX-License-Identifier: LGPL-3.0-or-later

Build docs developers (and LLMs) love

Get started for freeTalk to us