How to Contribute

Thank you for your interest in contributing to opinf! Before you begin, please review our Code of Conduct.

Summary

• Changes to the source code must be accompanied with updates to corresponding unit tests and documentation.

• Use tox to run tests while developing:

  • tox -e style checks that source code and tests follow the style guide.

  • tox (without arguments) executes all unit tests.

  • tox -e literature,docs compiles the documentation.

• When all tests pass, open a pull request to the main branch on GitHub.

Setup

Attention

Contributing to this project requires familiarity with GitHub and git. If you are unfamiliar with either, start with the GitHub tutorial or the git tutorial.

Now that you are a git expert, fork the GitHub repository and clone your fork. Add the original repository as an upstream remote.

git clone git@github.com:<username>/rom-operator-inference-Python3.git OpInf
cd OpInf
git remote add upstream git@github.com:Willcox-Research-Group/rom-operator-inference-Python3.git

Like most Python packages, opinf has a few software dependencies. To avoid conflicts with other installed packages, we recommend installing opinf within a new conda environment (recommended) or virtual Python environment .

# Make a fresh conda environment and install Python 3.12.
conda create -n opinfdev python=3.12

Be sure to activate the environment before using pip or other installation tools. Then, install the package with developer dependencies.

# Activate the conda environment (updates the PATH).
$ conda activate opinfdev

# Verify python is now linked to the conda environment.
(opinfdev) $ which python3
/path/to/your/conda/envs/opinfdev/bin/python3
(opinfdev) $ python3 --version
Python 3.12.3

# Install the package and its dependencies in development mode.
(opinfdev) $ python3 -m pip install -e ".[dev]"

Style checks, unit tests, and documentation builds are managed with tox. For each of these tasks, tox creates a new virtual environment, installs the dependencies (e.g., pytest for running unit tests), and executes the task recipe.

Note

Unit tests are executed for Python 3.9 through 3.12 if they are installed on your system. The best way to install multiple Python versions varies by platform; for MacOS, we suggest using Homebrew.

# After installing Homebrew:
brew install python@3.9
brew install python@3.10
brew install python@3.11
brew install python@3.12

Finally, to ensure that new additions follow code standards and conventions, install the git pre-commit hook with the following command.

(opinfdev) $ pre-commit install

Important

Don’t skip this step! It will help prevent automated tests from failing when a pull request is made.

Branches and Workflow

The source repository has three special branches:

• main is the most up-to-date version of the code. Tags on the main branch correspond to public PyPi releases.

• gh-pages contains only the current build files for this documentation. This branch is updated by maintainers only.

• data contains only data files used in documentation demos.

To contribute, get synced with the main branch, then start a new branch for making active changes.

git pull upstream main        # Synchronize main with the source repository.
git branch <mynewbranch>      # Create a new branch to make edits from.
git switch <mynewbranch>      # Switch to the new branch to do work.

You are now ready to make edits on your newly created local branch. When you’re ready, create a pull request to merge the changes into Willcox-Research-Group:main.

Repository Organization

Note

Full examples, like the one listed on the left under the Tutorials heading, are part of the documentation. They should be written as Jupyter notebooks and placed in docs/content/tutorials/.

The GitHub repository is organized as follows.

• src/opinf/ contains the actual package code.

• tests/ contains tests to be run with pytest (via tox). The file structure of tests/ should mirror the file structure of src/opinf/. See Testing Source Code.

• docs/ contains documentation (including this page!). See Documentation.

Acceptance Standards

Changes are not usually be accepted until the following tests pass.

1. tox: write or update tests to validate your additions or changes, preferably with full line coverage.

2. tox -e style: write readable code that conforms to our style guide.

3. tox -e literature,docs: write or update documentation based on your changes.

Tip

The Makefile has recipes for these commands, run make to see options. See makefiletutorial.com for an overview of Makefile syntax and usage.