Skip to content

How to contribute (WIP)

Jump to bottom
Tom Urbach edited this page Jun 15, 2021 · 1 revision

This tutorial assumes that you are familiar with Python, git, github, and conda. If any of the following is not making sense, please post an issue with your question/suggestion.

Prerequisites

  • a Linux machine
  • git
  • conda

Setup

  1. Clone the latest fitgrid development branch from github:

    git clone --branch dev --single-branch https://github.com/kutaslab/fitgrid.git/dev

  2. Checkout a new working branch (but call it something sensible, not new-branch).

    git checkout -b new-branch

  3. Create and activate a conda development environment, it will likely take a while to install all the latest fitgrid dependencies.

    conda create -n fitgrid_compat -c kutaslab/label/pre-release -c defaults -c conda-forge -c ejolly -y
conda activate fitgrid_compat

  4. Install fitgrid in development mode so import fitgrid imports the changes you make to the source:

    pip install -e .

Making changes

  1. If you are working on a new feature or fixing a bug, add tests that will pass when the feature is added or the bug is fixed.

  2. Make your changes.

  3. Run pytest regularly as you are iterating on your feature/bugfix.

  4. fitgrid uses a code formatter called Black to enforce a uniform code style. Install it if you don't have it:

    conda install black

    We use the draconian convention of a maximum line length of 79, so run the following to format your code accordingly:

    black -S --line-length=79 .

    -S is there to allow both single quotes and double quotes for strings.

  5. Make sure all tests pass and your code is formatted appropriately. You are almost ready to submit your changes. While you've been working on your branch, someone might have merged something into dev, so you need to ensure you are up-to-date:

    git checkout dev
git pull
git checkout - # switch back to your branch
git rebase dev

  6. Assuming the previous step didn't fail, you are now ready to submit your changes and push your branch to the repo:

    git push --set-upstream origin new-branch

    where new-branch is the name of your branch.

  7. Check the Actions tab on https://github.com/kutaslab/fitgrid/actions and make sure your new branch is passing all the Actions tests.

  8. If all Actions pass, use the the GitHub interface, and make a pull request to dev.

Clone this wiki locally