Contributing¶

Thank you for your interest in improving ridgeplot! 🚀

We really appreciate you taking the time to help make this project better for everyone.

The contribution process for ridgeplot usually starts with filing a GitHub issue. We define two main categories of issues, each with its own issue template

⭐ Feature request: Suggest a new idea or enhancement to ridgeplot
🐛 Bug report: Report an issue you encountered with ridgeplot

For broader discussions, questions, or general feedback, please head over to our GitHub Discussions page.

Please note that this is a volunteer-run project, and we may not be able to respond to every issue or pull request immediately. Our response time may vary, but we appreciate your patience and will try to get back to you as soon as possible.

After we’ve triaged your issue and an implementation strategy has been agreed on by a ridgeplot maintainer, the next step is to introduce your changes as a pull request (see Pull Request Workflow). Once the pull request is merged, the changes will be automatically included in the next ridgeplot release. Every significant change should be listed in the ridgeplot Changelog.

The following is a set of (slightly opinionated) rules and general guidelines for contributing to ridgeplot. Emphasis on guidelines, not rules. Use your best judgment, and feel free to propose changes to this document if you think something could be improved.

Development environment¶

Here are our guidelines for setting a working development environment. Most of the steps have been abstracted away using the make build automation tool. Feel free to peak inside the Makefile to see exactly what is being run, and in which order.

First, you will need to clone this repository. For this, make sure you have a GitHub account, fork ridgeplot by clicking the Fork button, and clone the main repository locally (e.g., using SSH)

git clone git@github.com:tpvasconcelos/ridgeplot.git
cd ridgeplot

You will also need to add your fork as a remote to push your work to. Replace {username} with your GitHub username.

git remote add fork git@github.com:{username}/ridgeplot.git

Bootstrapping the development environment¶

The following command will:

Delete any existing environment artifacts (e.g., .venv, .tox, .pytest_cache, etc.)
Create a new virtual environment under .venv
Install ridgeplot in editable mode along with all it’s development dependencies
Set up and install all pre-commit hooks.

make init

The default and recommended base Python is python3.9. However, if you encounter any issues or don’t have this specific version installed on your system, you can change by it exporting the BASE_PYTHON environment variable to a valid executable you do have installed. Please note that we no longer support any Python versions lower than 3.9. For example, to use python3.13, you should run:

BASE_PYTHON=python3.13 make init

If you need to use jupyter in this environment, run the following command:

make jupyter-init

Note

Make sure you always work within this virtual environment (e.g., $ source .venv/bin/activate). We also recommend that you set up your IDE to always point to this Python interpreter. If you are unsure how to do this, please refer to the documentation of your specific IDE, and get comfortable using virtual environments in Python. You can thank us later! 🐍

Pull Request Workflow¶

If you’re reading this, it means you’re probably getting ready to submit a pull request (or at least thinking about it). Either way, congrats! and we thank you in advance for putting in the time and effort to contribute to ridgeplot! 🎉

Always confirm that you have properly configured your name and email address in your git environment. This information will be used to identify you as a contributor in the project’s commit history.
```
# e.g., to set your name and email address globally
git config --global user.name '<Your name>'
git config --global user.email '<Your email address>'
```

Branch off the main branch.

# e.g., to create a new branch named `feat/awesome-feature`
git fetch origin
git switch -c feat/awesome-feature origin/main

Implement and commit your changes 🚀
Make sure all CI checks are passing locally (see Continuous Integration below).
```
tox -m static tests
```

Push your changes to your fork

git push --set-upstream fork <YOUR-BRANCH-NAME>

Create a pull request, and remember to update the pull request’s description with relevant notes on the changes implemented, and link to relevant issues (e.g., fixes #XXX or closes #XXX).
At this point, you’ll probably also want to add an entry to docs/reference/changelog.md summarising the changes in this pull request. The entry should follow the same style and format as other entries, i.e.

- Your summary here. ({gh-issue}XXX)

where XXX should be replaced with your PR’s number. If you think that the changes in this pull request do not warrant a changelog entry (e.g., simply fixing a typo), please state it in your pull request’s description. In such cases, a maintainer should add a skip news label to make the CI checks pass.
Wait for all remote CI checks to pass and for a ridgeplot maintainer to review your changes. If you’re not done with your changes yet, you can set your pull request to a Draft state, which will signal to the maintainers that you’re still working on it. Just remember to mark it as ready for review when you’re done!
Once your pull request is approved, it will be merged into the main branch, and your changes will be automatically included in the next ridgeplot release. 🚀

Continuous Integration¶

Continuous Integration (CI): automatically builds, tests, and integrates code changes within a shared repository.

—GitHub: CI/CD: The what, why, and how

The first step to Continuous Integration (CI) is having a version control system (VCS) in place. Luckily, you don’t have to worry about that! As you have astutely noticed, we use git and host on GitHub.

On top of this, we also run a series of integration approval steps that allow us to ship changes faster and with greater confidence that we won’t be breaking things for users down the line. In order to achieve this, we run a suite of automated tests and coverage reports, as well as a series of linters and type checkers.

Running it locally¶

Our tool of choice for configuring and reliably run all integration checks is Tox, which allows us to run each step in reproducible isolated virtual environments.

To trigger all checks, simply run:

tox -m static tests

…yes, it’s that simple! 🤓

Note that this could take a while the first time you run the command, since it will have to create all the required virtual environments (along with their dependencies) for each CI step.

The configuration for Tox and each test environment can be found in tox.ini.

If you need more control over which set of checks is running, take a look at the following two sections.

Tests and coverage reports¶

We use pytest as our testing framework, and Coverage.py to track and measure code coverage.

To trigger all test suites with coverage reports, run:

tox -m tests

If you need more control over which tests are running, or which flags are being passed to pytest, you can also invoke tox -e pytest -- <PYTEST_FLAGS>. For instance, to run only the tests in the tests/unit/test_init.py file without coverage, you could run:

tox -e pytest -- tests/unit/test_init.py --no-cov

For more details on how these checks are configured, take a look at the pytest.ini, .coveragerc, and/or tox.ini configuration files.

Static checks¶

This project uses pre-commit hooks to check and automatically fix any linting code formatting issues. These checks are triggered against all staged files before creating any git commit. To manually trigger all pre-commit hooks against all files, run:

pre-commit run --all-files

For more information on all the checks being run here, take a look inside the .pre-commit-config.yaml configuration file.

The only static check that is not run by pre-commit is pyright, which is too expensive to run on every commit. To run pyright against all files, run:

tox -e typing

Just like with pytest, you can also pass extra positional arguments to pyright by running tox -e typing -- <PYRIGHT_FLAGS>.

To trigger all static checks, run:

tox -m static

GitHub Actions¶

We use GitHub Actions to automatically run all integration approval steps defined with Tox on every push or pull request event. These checks run on all major operating systems and all supported Python versions. Coverage data is also uploaded to Codecov here. Check .github/workflows for more details.

Additionally, we use CodeQL to automatically check for security vulnerabilities in the codebase. This check is set to run every day but also on every push or pull request event. Check .github/workflows/codeql.yml for more details.

Finally, we have a small workflow (see .github/workflows/check-release-notes.yml) that checks if the PR author remembered to add an entry to the changelog. If the PR does not warrant a changelog entry, the author can add a skip news label to make the CI checks pass.

Tools and software¶

Here is a quick overview of ~~all~~ most of the CI tools and software used in this project, along with their respective configuration files. If you have any questions or need help with any of these tools, feel free to ask for help from the community by commenting on your issue or pull request.

Tool	Category	config files	Details
Tox	🔧 Orchestration	tox.ini	We use Tox to reliably run all integration approval steps in reproducible isolated virtual environments.
GitHub Actions	🔧 Orchestration	.github/workflows/ci.yml	Workflow automation for GitHub. We use it to automatically run all integration approval steps on every push or pull request event.
Make	🔧 Orchestration	Makefile	A build automation tool that we (mis)use to abstract away some bootstrapping and development environment setup steps.
git	🕰 VCS	.gitignore	The project’s version control system.
pytest	🧪 Testing	pytest.ini	Testing framework for python code.
Coverage.py	📊 Coverage	.coveragerc	The code coverage tool for Python
Codecov	📊 Coverage	.github/workflows/ci.yml	An external services for tracking, monitoring, and alerting on code coverage metrics.
pre-commit	💅 Linting	.pre-commit-config.yaml	Used to to automatically check and fix any formatting rules on every commit.
pyright	💅 Linting	pyrightconfig.json	A static type checker for Python. We use quite a strict configuration here, which can be tricky at times. Feel free to ask for help from the community by commenting on your issue or pull request.
ruff	💅 Linting	ruff.toml	“An extremely fast Python linter and code formatter, written in Rust.” For this project, ruff replaced black, Flake8 (+plugins), isort, pydocstyle, pyupgrade, and autoflake with a single (and faster) tool.
EditorConfig	💅 Linting	.editorconfig	This repository uses the `.editorconfig` standard configuration file, which aims to ensure consistent style across multiple programming environments.
bumpversion	📦 Packaging	.bumpversion.cfg	A small command line tool to simplify releasing software by updating all version strings in your source code by the correct increment.
setuptools	📦 Packaging	pyproject.toml and MANIFEST.in	`MANIFEST.in` tells `setuptools` which files to include in the distribution. `pyproject.toml` is the new standard for defining static package metadata.
readthedocs	📚 Documentation	.readthedocs.yaml and .github/workflows/readthedocs-preview.yml	An open-source documentation hosting platform. We use it to automatically build and deploy the documentation for this project.

Code of Conduct¶

Please remember to read and follow our standard Code of Conduct. 🤝