Skip to content

View or edit on GitHub

This page is synchronized from doc/How-we-use-Git.md. Last modified on 2025-12-09 00:30 CET by Trase Admin. Please view or edit the original file there; changes should be reflected here after a midnight build (CET time), or manually triggering it with a GitHub action (link).

How we use Git

Trase relies heavily on Git and GitHub for version control and collaboration.

Key principles:

  • Monorepo: All code is stored in a single Git repository.
  • Branching: Avoid pushing directly to master. Use branches and pull requests (PRs).
  • Master is Production: The "master" branch should reflect the current, active state of Trase, including scripts behind any published data.
  • Archive inactive code: Use git rm rather than keeping old scripts in the repo.
  • Review before merging: PRs should be reviewed when possible before merging into master.

Slides from our Git at Trase training are available in 2025 Git training (Google drive).

Standard workflow

[!NOTE] The advice in this section applies for code directly relevant to data production, and for any analysis related to data production. However, for standalone R&D projects that do not involve other team members or publically released data, it is okay to store your code locally and just push it to GitHub when it is finished. You do not need to create a new directory for an R&D project, it can fit into the existing structure (scripts in data/, analyses in products/).

Each time you want to work on a new task, you should follow this workflow:

  1. Sync with the latest master to make sure your local copy of the master branch is up to date with GitHub.

  2. Create a new branch based off master.

    The branch name should include your name/initials and a brief description of the task, e.g. NF_cote_divoire_cocoa_deforestation_metrics_q2_2025. 4. Push the branch to GitHub and create a draft pull request. Even though it is empty, this indicates to others that you are working on this task. 5. Push your changes to GitHub daily.

    Commit your changes often and push to GitHub at least once a day, even if it’s not finished. This ensures somebody else can take over if you need to leave suddenly. 7. Mark the pull request as "ready for review" when you are ready to merge your branch into master.

    If you think a human review is needed then request a reviewer. There are no hard rules about code reviews, just use your judgment and ask a team member if unsure. 9. Merge the pull request once the code review (if needed) is complete and the automated tests pass.

    If you decide that changes should not be merged, close the pull request and delete the branch.

The time between creating the branch and merging or closing the pull request should be no more than two weeks. If it has taken longer than this, it is likely that your pull request contains too many changes, which makes it difficult for others to review.

Automated checks

Before merging a pull request to master we do require that some automatic code checks (linting and Python tests) pass.

You can run these checks locally as follows:

  • Linting: pre-commit run --all-files
  • Python tests: pytest .
  • More Python tests, to check changed files for errors (you need to run this from the root of the repo): poetry run pip install "pylint==3.3.*" && git diff --name-only HEAD master | grep '\.py$' | xargs pylint --errors-only --disable=import-error,no-value-for-parameter,no-member

Interacting with Git

You may consider using Git on the command-line: this may help you gain a better understanding of how Git works. However, it is also a steeper learning curve and may be more of a hindrance than a help, and so you may prefer to use a point-and-click visual tool such as those in RStudio or PyCharm, or a standalone tool like GitKraken.

Code review process

Code reviews help ensure quality and share knowledge across the team. There are two roles: the author (person who wrote the code) and one or more reviewers (teammates who provide feedback).

The author should make a judgement call about whether a code review is needed in the first place. They are ultimately responsible for implementing any changes suggested by the reviewer(s), and for merging the pull request once it has been approved.

The responsibilities of the reviewer are:

  • To respond to a code review request quickly
  • To communicate in an open, clear and respectful way
  • Make a best effort to identify bugs and potential security issues

Why can't I merge pull requests?

It may be that you do not have a sufficiently permissable role. The maintain role is required to merge pull requests. If the continuous integration checks fail, then only somebody with the admin role can merge the pull request.

Useful Resources

If you are new to Git or GitHub, here are some useful guides: