Developer guide

If you’re a researcher and you found Harmony useful for your research, please cite us. If you encounter a problem, a bug, or a feature which you would like us to implement, please raise an issue on Github or message us on Discord.

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 four main repositories on Github under the harmonydata organisation:

Harmony Python library: https://github.com/harmonydata/harmony - this is everything to do with the NLP logic of Harmony. This is the main core library and the Python package which is on Pypi.
Harmony API: https://github.com/harmonydata/harmonyapi - the Python API runs with Pydantic and Fast API and is running on an on-prem server enabling the web app to work
Harmony front end: https://github.com/harmonydata - this is everything to do with the front end and graphical interface of Harmony. We welcome feedback and contributions on front end and UX issues.
R: https://github.com/harmonydata/harmony_r - the R port is on CRAN and it is slightly less mature than Python so we really appreciate if you can give the R package some TLC.

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

Testing what you’ve done

After you’ve made a change, please run the unit tests in any part of the code base that your changes might have affected, either directly or indirectly, to see if anything is broken:

the Harmony module https://github.com/harmonydata/harmony/tree/main/tests
the API https://github.com/harmonydata/harmonyapi/tree/main/tests

Please try and run the tool e.g. front end and back end to check if you can get the tool working still with your changes:

Python on Windows installation video (only relevant if you were working on Python)
Python on Linux (Ubuntu) installation video (only relevant if you were working on Python)
R on Windows installation video (only relevant if you were working on R)

Hackathons, coding challenges and events

Please contribute to our hackathons and coding challenges to help improve the tool. We appreciate coming to give talks at events such as Women In Data™️, AI|DL, MethodsCon Futures, Pydata, Lifecourse, and AI Camp. If you run a similar meetup or community group we are willing to come and talk.

Process of forking and making a pull request

If you are able to fix an issue, please feel free to submit your code back to the project by making a pull request (PR) but if you don’t know how to do that, don’t worry! You can always send us your work on Discord or by email. Here’s a brief overview of the steps for making a pull request.

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.
Clone your fork of the Harmony repo from your GitHub account to your local disk:

git clone git@github.com:harmonydata/harmony.git

cd harmony

Configure and link the remote for your fork to the upstream repository:

git remote -v

git remote add upstream <https://github.com/harmonydata/harmony.git>

Verify the new upstream repository you’ve specified for your fork:

git remote -v

\> origin <https://github.com/<username>/Harmony.git> (fetch)

\> origin <https://github.com/<username>/Harmony.git> (push)

\> upstream <https://github.com/harmonydata/harmony.git> (fetch)

\> upstream <https://github.com/harmonydata/harmony.git> (push)

Sync the main branch of your fork with the upstream repository:

git fetch upstream

git checkout main

git merge upstream/main

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.

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

When finished, push the changes to your GitHub account with:

git push --set-upstream origin my-feature-branch

Follow these instructions to create a pull request from your fork. If your work is still work in progress, open a draft pull request.

Note

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

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