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 Makefile shortcuts while developing:

  • make lint checks that source code and tests follow the style guide.

  • make test executes all unit tests.

  • make docs compiles the documentation.

• When all tests pass, make 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 https://<username>@github.com/<username>/rom-operator-inference-Python3
cd rom-operator-inference-Python3
git remote add upstream https://<username>@github.com/Willcox-Research-Group/rom-operator-inference-Python3

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.11.
conda create -n opinf3.11 python=3.11

Be sure to activate the environment before using pip or other installation tools.

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

# Verify python is now linked to the conda environment.
$ which python3
/path/to/your/conda/envs/opinf3.11/bin/python3
$ python3 --version
Python 3.11.8

Branches and Workflow

The source repository has two 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.

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

The GitHub repository is organized as follows.

Note

Full examples, like the one you see 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/.

• src/opinf/ contains the actual package code, see the Source Code Guide.

• tests/ contains tests to be run with pytest. The file structure of tests/ should mirror the file structure of src/opinf/. See Testing.

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

Acceptance Standards

Tip

The file Makefile defines routines that are triggered by the make command line utility. The aptly named makefiletutorial.com gives a good overview of Makefile syntax and usage.

For any changes to be accepted, they need to address three things.

1. Source Code. Write readable code that conforms to our style guide: make lint must succeed.

2. Unit tests. Write or update tests to validate your additions or changes: make test must succeed with full line coverage.

3. Documentation. Write or update documentation based on your changes: make docs must succeed.