Developer guide

Git and GitHub workflow

The preferred workflow for contributing to Harmony’s repository is to fork the main repository on GitHub, clone, and develop on a new branch.

Please read our general guide about contributing to Harmony.

We have three main repositories on Github under the harmonydata organisation:

This contributor guide focuses on the Python library, but you could follow the same steps for the other repositories.

  1. Fork the main project repository by clicking on the ‘Fork’ button near the top right of the page. This creates a copy of the code under your GitHub user account. For more details on how to fork a repository see this guide.
  2. Clone your fork of the Harmony repo from your GitHub account to your local disk:
git clone

cd harmony
  1. Configure and link the remote for your fork to the upstream repository:
git remote -v

git remote add upstream <>
  1. Verify the new upstream repository you’ve specified for your fork:
git remote -v

\> origin <<username>/Harmony.git> (fetch)

\> origin <<username>/Harmony.git> (push)

\> upstream <> (fetch)

\> upstream <> (push)
  1. Sync the main branch of your fork with the upstream repository:
git fetch upstream

git checkout main

git merge upstream/main
  1. Create a new feature branch from the main branch to hold your changes:
git checkout main

git checkout -b <feature-branch>

Always use a feature branch. It’s good practice to never work on the main branch! Name the feature branch after your contribution.

  1. Develop your contribution on your feature branch. Add changed files using git add and then git commit files to record your changes in Git:
git add <modified_files>

git commit
  1. When finished, push the changes to your GitHub account with:
git push --set-upstream origin my-feature-branch
  1. Follow these instructions to create a pull request from your fork. If your work is still work in progress, open a draft pull request.


We recommend to open a pull request early, so that other contributors become aware of your work and can give you feedback early on.

  1. To add more changes, simply repeat steps 7 - 8. Pull requests are updated automatically if you push new changes to the same branch.


If any of the above seems like magic to you, look up the Git documentation. If you get stuck, chat with us on Discord, or contact us at

Signup to our newsletter

The latest news on data harmonisation project.

Please select all the ways you would like to hear from Harmony project:

You can unsubscribe at any time by clicking the link in the footer of our emails. For information about our privacy practices, please visit our website. We use Mailchimp as our marketing platform. By clicking below to subscribe, you acknowledge that your information will be transferred to Mailchimp for processing. Learn more about Mailchimp's privacy practices.