Contributing#

Open an issue#

You don’t have to do any coding to contribute. Reporting bugs and requesting new features via GitHub Issues is a very valuable contribution. To open a new issue, head over to the relevant issue page:

Dev environment setup#

If you plan to contribute docs or code, you will need a local development environment.

Fork and clone the repo#

First, fork the repository on GitHub: pangeo-forge/pangeo-forge-recipes. Then, checkout your fork locally:

git clone git@github.com:{{ your_username }}/pangeo-forge-recipes.git
cd pangeo-forge-recipes

Note

From now on, we will assume all shell commands are from within the pangeo-forge-recipes directory.

Finally, create a new git remote pointing to the upstream repo:

git remote add upstream git@github.com:pangeo-forge/pangeo-forge-recipes.git

Create a virtual environment#

We strongly recommend creating an isolated virtual environment, which ensures you have all the correct dependencies and tools for development.

This can be either a Conda environment or a Python venv.

Set up pre-commit#

We use pre-commit to manage code linting and style. Once you have a virtual environment created and activated, run the following commands (from the repo root) to setup pre-commit:

pip install pre-commit
pre-commit install

Development lifecycle#

Create a new branch#

When you are ready to make changes, start by creating a new branch from main:

git checkout -b my-cool-feature

Commit changes#

Make changes using your favorite text editor, and commit them as you go along:

git add path/to/changed_files
git commit -m 'informative commit message'

Open a PR#

When you are ready for feedback on your changes, push them to GitHub:

git push origin my-cool-feature

And then open a Pull Request against main with your changes.

Cleanup#

Once your PR is merged, rebase your local main to match changes upstream:

git checkout main
git fetch upstream
git rebase upstream/main

And delete the feature branch:

git branch -d my-cool-feature

Contributing: docs#

We strongly encourage contributions to make the documentation clearer and more complete.

Install dependencies#

With your virtual environment activated, run:

pip install -r docs/requirements.txt

Build the docs#

To build the documentation:

cd docs
make html

View the docs#

Serving the documentation locally (starting from the docs directory):

cd _build/html; python -m http.server; cd ../..
# press ctrl-C to exit

Alternatively you can open docs/_build/html/index.html in your web browser.

Contributing: code#

If you’re ready to start contributing to the code, here is where to start.

Install dependencies#

With your virtual environment activated, run:

pip install -e ".[dev]"

Run the test suite#

The tests are as important as the code itself. They verify that pangeo-forge-recipes actually works.

To run the test suite:

pytest tests -v

Releasing#

To make a new release, first add Release Notes for the release to the docs.

Then just go to pangeo-forge/pangeo-forge-recipes and click “Draft a new release”.

The release.yaml workflow should take care of the rest.