Contributing guide

Guidelines to ensure smooth collaboration and maintain a clean and structured codebase.

Branching model

  • main: The stable production branch, corresponding to the official releases.

  • dev: The development branch. It contains integrated features and bug fixes, pending final validation through manual testing on real data before going into production.

Workflow

New branch

Always create your working branch from dev:

git checkout dev
git pull
git checkout -b <type>/<short_task_name>

Note

Branch names should follow this pattern: <type>/<short_task_name>

Where <type> can be:

  • feat: New feature

  • fix: Bug fix

  • doc: Documentation update

  • test: Adding missing tests

  • chore: Technical tasks with no impact on functionality (e.g., updating dependencies, CI config, build scripts, etc.)

Commit messages

Use clear and conventional commit messages. We recommend following Conventional Commits:

Template:

<type>(<scope>): Summary title #<issue_number>

- List of task or bugfix done in this commit

Example:

doc(contributor): Write file for commit good practices #167

- Content reminder
- Message template
- This example

Note

During the Pull Request to dev, the “squash & merge” method will be used, so this clear message is only needed for the squash commit.

Pull Request (PR)

Once your development is complete:

git push origin <your-branch-name>

Then:

  • Open a pull request to dev

  • A [PR template is provided](file:///home/xdevos/Repositories/pyHi-M/traceratops/docs/build/html/contribute/checklist/pr_template_COPY.html) with a checklist to support the validation process

  • Select “Squash & merge” when merging the PR

  • Use a clear and descriptive PR title — it will become the commit message on dev

[OPTIONAL] Continuing development (while PR is pending)

Warning

Avoid working again on the same branch that is already under review.

While waiting for your PR to be reviewed and merged, you can continue development by creating a new branch from dev (recommended) or from your previous branch if you need the latest update to continue working.

git checkout dev
git pull
git checkout -b <type>/<new_task>

Resolving merge conflicts

Merge conflicts may happen when:

  • Two PRs modify the same part of the codebase.

  • A long time has passed between when your branch was created and when it’s merged.

To resolve conflicts:

  1. Pull the latest dev into your branch:

git checkout <your-branch>
git pull origin dev

  1. Git will notify you of conflicts — open the conflicting files, resolve manually, then:

git add <resolved-files>
git commit

  1. Push the updated branch:

git push origin <your-branch>

If the PR is not closed, it will automatically integrate your new conflict resolution commit.

Testing & Validation

  • Make sure all tests pass before submitting a PR.

  • Add tests for any new feature or fix when possible.

  • Manual tests on real (big) data are expected before merging into main.

Communication

  • Use GitHub Issues for reporting bugs or proposing features.

  • Use discussions or team communication tools (Zulip) for technical coordination.

Thank you for contributing!