Skip to content

Contributing Guidelines

We're so excited that you're interested in contributing to Neurobagel! 🥳

We appreciate all contributions, and hope that the below guidelines will make it as easy as possible for you to contribute to the Neurobagel codebase and to ensure your contribution can be easily integrated.

Contributing through GitHub

In order to contribute to Neurobagel, you'll need to set up a GitHub account and sign in. Here are some instructions to help you get started.

Identifying an issue to contribute to

The best way to get started contributing is to explore the list of open issues in one of our GitHub repositories. (For example, see the open issues for the Neurobagel API.)

When you are ready to contribute, we welcome you to join the conversation through one of these issues, or open a new issue referencing a change you would like to see or contribute. Ensuring that a relevant issue is open before you start contributing code is important because it allows others in the project to discuss your idea and tell you where your contribution would be the most helpful.

  • If the issue you want to work on already exists: Comment on the open issue to indicate you would like to work on it, along with any clarification/implementation questions you have

    • If someone is already assigned to the issue, the task is actively being worked on and a solution will soon be proposed. Feel free to share some helpful resources or pointers that may be interesting to the person who is working the issue, and/or check back in a couple of days.

  • If the issue you want to work on does not exist: Open a new issue describing your proposed change and why it is necessary/beneficial. The more detail here, the better!

This allows members of the Neurobagel developer team to confirm that you will not be overlapping with currently active work and that everyone is on the same page about the task to be accomplished.

If you would like to contribute but are not sure where to start, we recommend looking for open issues with the following labels:

good first issue Issue that is good for a new or beginner contributor, as it does not involve a steep learning curve or advanced understanding of the codebase. (Please note: if you're a seasoned contributor, we would appreciate if you could select a different issue to work on to keep these available for less experienced folks!)

PR welcome Issue that is not an internal priority, but external pull requests to address it are welcome.

quick fix: Issue that should involve minimal planning or implementation work, given an understanding of the relevant code.

Making a change

All Neurobagel issues are expected to be addressed through pull requests.

As an external contributor, the process you would follow to make your proposed changes should look something like this:

1. Fork the relevant Neurobagel repository to your profile.

2. Clone your fork of the Neurobagel repository to your local machine.

To keep up with changes in the Neurobagel repository while you work and avoid merge conflicts later on, make sure to:

3. Set up a development environment.

Refer to the README of the Neurobagel repository you are contributing to for instructions on setting up a development environment so you can test any local code changes you make. Note that the steps to set up a development environment (usually under a "Local installation", "Manual installation", or "Development environment" section) are generally different than those used to install the tool purely as a user, which usually appears at the top of the README.

For example, for the Neurobagel CLI:

Follow repository code style

Most Neurobagel repositories use tools to apply automatic code formatting and linting according to the project's code style, which are typically configured (but not automatically enabled) in the development environment for these repositories. At this point, please follow the repository instructions to set up these tools before you begin your work to ensure your contribution matches the existing code.

For example, our repositories written in Python have pre-commit configured for this purpose.

To tell pre-commit to run on any local changes you make, run the following from the repository root of your local clone: 

pre-commit install

Now, a number of code linters and formatters will run automatically when you attempt to make a commit, which will keep your changes consistent with the rest of the codebase.

4. Create a new branch to make the proposed changes

Please consider using descriptive branch names. Some examples:

  • <username>/<issue-identifier> (jsmith/fix-1234)
  • <username>/<brief-change-title> (jsmith/add-logging, jsmith/enh/add-logging)

Once you are satisfied with your local changes, add, commit, and push them to your branch on your forked repository on GitHub.

5. Open a pull request

See the below sections for information on how to submit your pull request and what to expect in a pull request review.

Pull request guidelines

When you first open a pull request, you should automatically see a template in the pull request body that looks something like this that you can fill out. The template is designed to make it easier for maintainers to review your pull request, but feel free to add any additional information that you feel is useful or necessary.

Pull request titles should begin with a descriptive prefix (e.g., "[ENH] Implement check for presence of a session ID column"):

  • [ENH]: Feature improvements or additions
  • [REF]: Refactoring existing code
  • [TST]: Updating or adding a test
  • [CI]: Automation-related changes
  • [MNT]: General maintenance not covered by [REF], [TST], or [CI]
  • [INF]: Software or graph infrastructure-related changes
  • [FIX]: Bug fixes
  • [MODEL]: Updates or changes related to the Neurobagel data model
  • [DOC]: Documentation-only changes to a code repo (READMEs, within-code documentation, etc.)
    • Exception: changes to the documentation repo should use one of the below PR prefixes instead of [DOC]

Pull requests to the documentation repo

In PRs to the Neurobagel documentation, using the [DOC] title prefix is discouraged as it is too broad. Instead, for documentation content changes, the following prefixes can be used to specify the nature of the change:

  • [ENH]: Updating or adding new documentation
  • [REF]: Simplifying or restructuring documentation (i.e., pages, sections, paragraphs)
  • [FIX]: Fixing errors in the documentation

Pull request reviews

A maintainer will review each PR and may provide comments or suggestions for you to address.

Neurobagel PR reviews may use the following emoji signifiers:

🧑‍🍳: Ready to merge or approved without suggestions

🍒: Some optional/suggested changes that could be nice to have but are not required to merge

If (required) changes are requested, please re-request a review from the reviewer once the comments have been addressed.

When your pull request is approved

If you do not have write access to the repository: the reviewing Neurobagel maintainer is responsible for merging the PR.

If you have write access to the repository: the PR author is responsible for merging the PR.

Have a question about contributing?

At any point during a contribution, please do not hesitate to mention one of the core maintainers if you have a question or need further guidance, in either the issue or pull request.

If you have ideas for improving this page, please help us improve it by opening an issue 🎉.