Overview

Information for contributors

Quick start

  • Change current directory to the top level of your local Forest repository

  • Install Forest in editable mode: pip install -e .

  • Install development tools: pip install -r requirements.txt

  • Run code style checks: flake8

  • Run type hint checks: mypy -p forest

  • Run test suite: pytest

Documentation

Install required dependencies:

pip install -r docs/requirements.txt

Build the docs:

cd docs
make html

Open docs/_build/html/index.html in a web browser to check the results

General information

Python

GitHub

Development workflow:

  1. open an issue

  2. create a pull request

  3. merge pull request

  4. close issue

Branches

  • Follow the Gitflow Workflow for managing branches

  • Use descriptive names for branches

  • Keep branches short-lived to avoid potential merge conflicts

Pull requests

  • PRs:

    • are not just peer review but a way to communicate and learn about the code base

    • help build and pass on institutional knowledge, and keep default branch commit history clean

  • Keep PRs small (ideally, under 100 lines of code) and self-contained (code + tests + docs) to make reviews easier and faster

  • If you need to update an existing PR simply add commits to the corresponding feature branch instead of creating a new separate PR

  • Make sure your PR has the latest changes from the develop branch and that it passes the build process

How to create a PR:

  1. Create a feature branch off the default branch: git switch -c new-feature develop

  2. Push the new feature branch upstream to GitHub: git push --set-upstream origin new-feature

  3. Create a PR on GitHub:

    • write a short description

    • link to an issue if applicable

    • select a reviewer to notify

    • add labels

  4. Push commits to the upstream feature branch to update the PR or respond to reviewer’s comments

  5. Re-request the review after each round of changes

  6. After the PR is merged delete the feature branch in your local repository: git branch -d new-feature

How to review PR:

  1. Comment on proposed changes

  2. Resolve conversations when changes are addressed (either in code or comments)

  3. Approve the PR

  4. Squash and merge when all concerns are addressed and checks are completed

  5. Delete the feature branch on GitHub

Issues

  • Use the bug report issue template to report bugs

  • Assign to the right person

  • Don’t close issues until the fix is merged in to the default branch

Trees

For maximum happiness of the end users, we would like to point you to Forest naming conventions]. When analyzing digital phenotyping data, we recommend you to use the logging guidelines to record what happens (…and what fails…) during analyses. No worries, we have prepared some code snippets for you to use.

Tree naming

When you’ve finalized your contribution (hereafter ‘tree’), you can decide on a name for your tree. Please keep our tree naming conventions and reserved trees in mind.

External resources