Development Guide#

If you want to contribute to this project, please fork the repository, create a new branch, make changes, and submit a merge request (MR) for review and merge.

If you have a larger feature project in mind, please contact a senior developer to discuss the best approach and implementation.

GIT and MR guidelines#

  1. No direct pushes to master: Please create a new branch for each feature and avoid pushing directly to the master branch.

  2. Split large projects: Break down large projects into smaller, manageable pieces by creating multiple branches and submitting separate merge requests (MRs).

  3. Assign an Assignee: When creating an MR, assign a team member (not yourself) to review and merge the changes.

  4. Add a Reviewer (optional): For larger changes, consider adding an additional reviewer to provide feedback and approval before merging.

  5. Merge criteria: MRs will be merged once all reviewers have approved the changes, the pipeline has passed, and the assigned team member has merged the changes.

Some coding guidelines#

  1. Coding Standards: Please adhere to the PARALLAX coding standards.

  2. Python Modifications: The Python-specific rules that apply on top of those standards - covering layout, file naming, imports, docstrings, type hints, spelling and readability - are listed in Code Guidelines. Most of them are checked automatically by the pre-commit hooks, which are installed together with the TorX environment, so they run on every commit.

  3. Guidance on Coding Standards: Don’t worry if you’re not familiar with the coding standards initially. Once you submit a merge request (MR), the assigned team member and reviewers will help you implement any missing standards and ensure your code meets our requirements.

Tagging stable versions#

Before merging any breaking change, tag the current tip of master so the last working state stays reachable by name. This can be done entirely from the GitLab web UI (Repository > Tags) since the commit being tagged already lives on the remote. No local clone or git tag/git push is required, although the CLI equivalents work as well.

  1. Naming: latest_stable always points at the most recent stable commit. Once it is about to be superseded, its current target gets a permanent, numbered name instead: stable_XX_description, where XX is a zero-padded, incrementing two-digit number and description is a short snake_case summary of what the tag predates, e.g. stable_01_normalize_rename. We use the zero padding to sort the tags in incremental order.

  2. Moving latest_stable: git tags cannot be renamed in place, so moving latest_stable onto a new commit is a create-then-delete:

    • Create a new tag stable_XX_description targeting whatever commit latest_stable currently points at (in the GitLab UI, set the tag’s target to latest_stable before deleting it).

    • Delete the old latest_stable tag.

    • Create a new latest_stable tag targeting the current commit (e.g. the tip of master just before the breaking change).

  3. Checking out a tag: fetch tags and check out the name directly, e.g. to get the state just before the normalize rename:

    git fetch --tags
git checkout stable_01_normalize_rename

    This leaves you in a detached HEAD state (you are not on a branch), which is expected for inspecting or building from a fixed past state. If you want to make changes from there, create a branch first: git checkout -b my-branch stable_01_normalize_rename.