Overview

Information for contributors

Quick start

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

• Install Forest in editable mode along with development tools: pip install -e ".[dev]"

• Check code style: flake8

• Run static type checks: mypy

• Run the test suite: pytest

• Validate the citation file: cffconvert -i CITATION.cff --validate

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

• Forest Naming Conventions

• Exception handling

• Logging

• Ask questions about software design before writing the code

• Delete unnecessary code (don’t just comment it out)

• Rewrite code if necessary

• Write short functions that do one thing only

• Specify exact version numbers for dependencies (pin your requirements)

• Refactor the code and avoid copy-paste programming (Don’t Repeat Yourself)

• Write tests for all new code

Python

• Follow PEP 8, The Zen of Python, Google style guide for docstrings, and The Elements of Python Style guidelines

• Avoid one character names (except with lambda, generator expressions, and with unpacking when using _ as a throwaway character)

• Use double quotes for strings and use single quotes only to avoid backslashes in the string

• Alphabetize imports within blocks

• Use parentheses for continuations and method chaining

• Put a line break before a binary operator

• Use the logging module instead of print()

• Formatting log messages: logger.info("%s went %s wrong", 42, 'very')

• Continue writing code and comments all the way until the end of the line then indent appropriately

• Packaging Python Projects

Packaging and distribution

Create a release

• Update the version number in pyproject.toml

• Update the changelog in CHANGELOG.md

• Commit and push all local changes to GitHub

• Merge the develop branch into the main branch

• Create a tag for the release: git tag -a v1.1.0 -m "Release 1.1.0"

• Push the tag to GitHub: git push origin v1.1.0

• Create a release on GitHub

• Build and upload the distribution archives to Python Package Index (see below)

Upload to Python Package Index

• Use TestPyPI for testing that your package can be uploaded, downloaded, and installed correctly

• Register an account

• Create an API token (setting the “Scope” to “Entire account”)

• Add API token to your $HOME/.pypirc file

• Clear the build directory: rm -r dist

• Generate distribution archives: python -m build

• Check the results: twine check dist/*

• Upload distribution archives:

  • TestPyPI: twine upload --repository testpypi dist/*

  • PyPI: twine upload dist/*

• Install from TestPyPI to verify:

  • TestPyPI: pip install --index-url https://test.pypi.org/simple/ --no-deps beiwe-forest

  • PyPI: pip install beiwe-forest

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

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

Review a 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

• Best Practices for Scientific Computing

• Good enough practices in scientific computing

• Ten simple rules on writing clean and reliable open-source scientific software