Contributing

If you would like to simply get started developing please feel free to skip to the development environment section below.

Contributions are welcome, greatly appreciated, and will be appropriately acknowledged. If you are new to contributing to open source software please consider reviewing the open source guides and the brief descriptions below. Briefly, please feel free to engage a discussion or github issue, fork the repository, create a branch, make changes, ensure the code is linted and the tests pass, add documentation, where relevant, and submit a pull request. At this point the continuous integration workflows will run and we will engage a more detailed discussion in reviewing the changes.

Please note that pyrovelocity is still in the early stages of development. The current state of the documentation and repository are not complete with respect to the procedures for contributing outlined here; however, we plan to respect them as we continue to develop the project.

See

Types of Contributions

Report Bugs

Report bugs at https://github.com/pinellolab/pyrovelocity/issues.

If you are reporting a bug, please fill out the provided template including:

  • Your operating system name and version.
  • Any details about your local setup that might be helpful in troubleshooting.
  • Detailed steps to reproduce the bug.

Respond to existing issues

Review the history of both open and closed GitHub issues. If you would like to attempt to resolve an open issue please comment on the issue, fork the repository, create a branch with name format ##-subtitle, where ## is the issue number and subtitle is a word that is related to the issue. Run experiments and write tests from your local fork and then submit a pull request referencing the issue.

Write Documentation

If you would like to add or contribute to refining the documentation, please create an issue and submit a pull request with modifications to the documentation site, docstrings and doctests, or adding illustrative pytest tests. We attempt to loosely follow the diataxis recommendations for structuring technical documentation.

Submit Feedback

The best way to send feedback is to file an issue at https://github.com/pinellolab/pyrovelocity/issues.

If you are proposing a feature:

  • Explain in detail how it would work.
  • Keep the scope as narrow as possible, to make it easier to implement.
  • Remember that this is a volunteer-driven project, and that contributions are welcome :)

Development environment

Local

The following is a rough guide to setting up pyrovelocity for local development. Please do not hesitate to reach out if you need help setting up a development environment.

  1. Fork the pyrovelocity repository on GitHub.

  2. Clone your fork locally:

    $ git clone https://github.com/your_name_here/pyrovelocity.git

  3. Install poetry and install the repository source code in editable mode:

    poetry install --sync

  4. Create a branch for local development:

    git checkout -b 572-branch

    Now you can make your changes locally. You may need to familiarize yourself with using poetry to manage virtual environments and dependencies.

  5. When you’re done making changes, lint the code

    make lint

    and run the tests

    pytest

    These will be confirmed via the GitHub actions workflow that will run when you submit your pull request.

  6. Commit your changes and push your branch to GitHub:

    git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature

  7. Submit a pull request through the GitHub CLI or website targeting the beta branch.

    gh pr create \
-d \
-a "@me" \
-B beta \
-t "fix(model): add types for train_model function" \
-r username \
-b "- [x] added types to all parameters of the train_model function
- [x] enabled beartype and refactored associated tests
"

Nix

If you do not know what nix is and are interested in using this section, please see this video for a brief introduction to nix flakes.

One of the reasons you might be interested is that the instructions above only cover python dependencies. We use the nix package manager with a nix flake to manage both system dependencies and python dependencies together in a reproducible manner. This requires referencing the lock files in flake.lock and poetry.lock with the bridge provided by poetry2nix. At present there isn’t really another python package management system with a sufficiently detailed lock file to ensure that the python dependencies are reproducibly installable in concert with the system-level dependencies. Please see the rejected PEP 665 and other discussions that reference it as this may change in the near future. Taken together, this is why we currently use poetry to manage python dependencies in development environments.

Before proceeding ensure you have deactivated any virtual environments created with python-ecosystem tools. The nix flake integrates with direnv and provides a nix development shell that can be activated with

direnv allow

if you have nix and direnv installed. Please note this will require at least 10GB of free hard disk space to build and activate the environment. However, if your disk is within 50GB of being full, you may encounter a slow build process. Since you will need to enable the usage of nix flakes, you should either install the nix package manager with the Determinate Systems nix installer or update your /etc/nix/nix.conf or other active nix configuration to enable the nix-command and flakes features.

experimental-features = nix-command flakes

These features are not really “experimental” in any usual sense of the term so you should not be concerned about enabling them.

Container image

We provide a relatively minimal OCI image built with nix and dockerTools. It only supports linux x86-64, but can be run via rosetta emulation on macOS.

For example if you have a tool that provides a container runtime like nerdctl, podman, or docker installed

docker run --rm -it --entrypoint bash --platform=linux/amd64 ghcr.io/pinellolab/pyrovelocity:latest

Cloud

If you would like to access the cloud environment used to develop pyrovelocity, execute model training across many data set and model configurations, and track associated artifacts, please do not hesitate to reach out to us. We have limited availability, but would like to provide these resources to interested external contributors.

Pull Request Guidelines

Before you submit a pull request, check that it meets these guidelines:

  1. The pull request should include pytest tests and, where relevant, xdoctest doctests.
  2. If the pull request adds or significantly modifies functionality, the relevant Google-style docstrings and docs should likely be updated.
  3. The pull request should pass the CI execution for the primary supported python version (currently Python 3.10).