Contributing¶

Contributions are welcome and are greatly appreciated! Every little bit helps. Contributions include reporting/fixing bugs, proposing/implementing features (see our Issue Tracker), writing documentation in the codebase or on our website repo, and submitting feedback.

Developing pyribs¶

Ready to contribute? Here’s how to set up pyribs for local development.

Fork the pyribs repo on GitHub.

Clone the fork locally:

# With SSH:
git clone git@github.com:USERNAME/pyribs.git

# Without SSH:
git clone https://github.com/USERNAME/pyribs.git

Create a branch for local development:

git checkout -b name-of-bugfix-or-feature

Install the local copy and dev requirements into a virtual environment. For instance, with Conda, the following creates an environment at ./env.

cd pyribs
conda create --prefix ./env python=3.10  # 3.10 is the minimum version pyribs supports.
conda activate ./env
pip install -e .[all,dev]  # `all` contains dependencies for all extras of pyribs.
                           # `dev` contains development dependencies.

We roughly follow the Google Style Guide in our codebase. We use ruff and pylint to enforce code format and style. To automatically check for formatting and style on every commit, we use pre-commit. Pre-commit should have already been installed with .[dev] above. To set it up, run:
```
pre-commit install
```
Now make the appropriate changes locally. If relevant, make sure to write tests for your code in the tests/ folder.
Lint and auto-format your code using ruff and pylint. Note that pre-commit will automatically run these whenever you commit your code; you can also run it with pre-commit run. You can also run the following commands on the command line:
```
# Lint (without fixing).
ruff check FILES
pylint FILES
# Sort imports.
ruff check --select I --fix FILES
# Run formatter.
ruff format FILES
```

After making changes, check that the changes pass the tests:

pytest tests/
make test # ^ same as above

And to run the benchmarks:

pytest -c pytest_benchmark.ini
make benchmark # ^ same as above

Add your change to the changelog for the current version in HISTORY.md.

Commit the changes and push the branch to GitHub:

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

Submit a pull request through the GitHub web interface.

Instructions¶

Running a Subset of Tests¶

To run a subset of tests, use pytest with the directory name, such as:

pytest tests/core/archives

Documentation¶

Documentation is primarily written in Markdown, as we use the MyST Sphinx plugin.

To preview documentation, use:

make servedocs

This will open up a browser window and automatically reload as changes are made to the docs.

Adding a Tutorial¶

Tutorials are created in Jupyter notebooks that are stored under tutorials/ in the repo. To create a tutorial:

Write the notebook and save it under tutorials/. Notebooks may also be saved in a subdirectory of tutorials/, e.g., tutorials/features.
Use cell magic (e.g. %pip install ribs) to install pyribs and other dependencies.
- Installation cells tend to produce a lot of output. Make sure to clear this output in Jupyter lab so that it does not clutter the documentation.
- Choose your ribs extra carefully – in particular, if you use ribs.visualize in the tutorial, make sure to use %pip install ribs[visualize].
Before the main loop of the QD algorithm, include a line like total_itrs = 500 (any other integer will work). This line will be replaced during testing (see tests/tutorials.sh) in order to test that the notebook runs end-to-end. By default, the tests run the notebook with total_itrs = 5. If this tutorial needs more (or less), modify the switch-case statement in tests/tutorials.sh. The name TOTAL_ITRS can also be used.
Make sure that the only level 1 heading (e.g. # Awesome Tutorial) is the title at the top of the notebook. Subsequent titles should be level 2 (e.g. ## Level 2 Heading) or higher.
If linking to the pyribs documentation, make sure to link to pages in the latest version on ReadTheDocs, i.e. your links should start with https://docs.pyribs.org/en/latest/. Note that we do not use Sphinx autodoc (e.g., :class:) in the tutorials because such links do not work outside the pyribs website (e.g., on Google Colab).
Add an entry into the toctree in docs/tutorials.md and add it to one of the lists of tutorials.
Check that the tutorial shows up on the Tutorials page when serving the docs.
If the tutorial should be excluded from testing (e.g., because it takes too long to run), add it to the list of excluded tutorials in tests/tutorials_list.sh.
Create a PR into the website repo that adds the tutorial onto the home page, specifically this file. In the PR, include a square image that represents the tutorial.

Adding an Example¶

Examples are created in Python scripts stored under examples/ in the repo, and their source is shown in the docs. To create an example:

Write the Python script and save it under examples/.
Add any dependencies at the top of the script with a pip install command (see existing examples for a sample of how to do this).
Add a shell command to tests/examples.sh that calls the script with parameters that will make it run as quickly as possible. This helps us ensure that the script has basic correctness. Also call the install_deps function on the script file before running the script.
Add a Markdown file in the docs/examples directory with the same name as the Python file – if the example is examples/foobar.py, the Markdown file will be docs/examples/foobar.md.
Add a title to the Markdown file, such as:
```
# My Awesome Example
```

In the markdown file, include the following so that the source code of the example is displayed.

```{eval-rst}
.. literalinclude:: ../../examples/EXAMPLE.py
    :language: python
    :linenos:
```

Add any other relevant info to the Markdown file.
Add an entry into the toctree and list of examples in docs/examples.md.
Check that the example shows up on the Examples page when serving the docs.

Referencing Papers¶

When referencing papers, refer to them as Lastname YEAR, e.g. Smith 2004. Also, prefer to link to the paper’s website, rather than just the PDF.

Deploying¶

We roughly follow the trunk-based release model described here. Namely, we create release branches for minor versions (e.g., release/0.6.x) from our trunk (master branch). For patch releases, e.g., 0.6.2, we cherry pick bug fixes from master into the corresponding release branch.

Minor Versions¶

Check that the latest version of the docs is building on Read the Docs.
Create a PR into master after doing the following:
1. Update the version by editing __version__ in ribs/__init__.py.
2. Add all necessary info on the version to HISTORY.md.
Once the PR above has been merged, create a release branch from master called release/0.<NUM>.x, e.g., release/0.6.x.
On the release branch, switch tutorial links from latest to stable with:
```
make tutorial_links
```
See #300 for why we do this.
(Optional) On the release branch, run make release-test. This uploads the code to TestPyPI to check that the deployment works. If this fails, make fixes as appropriate.
Locally tag the head of the release branch, e.g.,
```
git tag v0.6.0 HEAD
```
Now push the tag with
```
git push --tags
```
Check that the version was deployed to PyPI. If it failed, delete the tag and make appropriate fixes on master. Then, cherry pick the fixes into the release branch. Finally, tag the HEAD again and push the tag.
Write up the release on GitHub, and attach it to the tag.

Patch Versions¶

Check that the latest version of the docs is building on Read the Docs.
Create a PR into master after doing the following:
1. Update the version by editing __version__ in ribs/__init__.py.
2. Add all necessary info on the version to HISTORY.md.
Once the PR above has been merged, checkout the release branch for the corresponding minor version, e.g., for 0.6.2, check out release/0.6.x.
On the release branch, cherry-pick the commit for the PR you just created. Also cherry pick any other bug fixes which need to be released in this patch.
On the release branch, edit HISTORY.md to remove any irrelevant history, e.g., if there are upcoming changes that will be included only in the next version.
If any tutorials were added in this release, run make tutorial_links to make the links point to the stable version of pyribs.
(Optional) On the release branch, run make release-test. This uploads the code to TestPyPI to check that the deployment works. If this fails, make fixes as appropriate.
Locally tag the head of the release branch, e.g.,
```
git tag v0.6.2 HEAD
```
Now push the tag with
```
git push --tags
```
Check that the version was deployed to PyPI. If it failed, delete the tag and make appropriate fixes on master. Then, cherry pick the fixes into the release branch. Finally, tag the HEAD again and push the tag.
Write up the release on GitHub, and attach it to the tag.