Skip to content

Contribution guidelines

Thanks for your interest in contributing to Ragna!

All Ragna development happens on GitHub.

If you'd like to contribute to an existing issue, make sure to comment on the issue to communicate your interest. If you're interested in something new, open an issue first to express interest and discuss the topic, implementation details, etc. with the Ragna Development Team.

Local development setup

To contribute to any part of the Ragna codebase (which includes documentation) you can setup a local development space with the following instructions.

Fork and clone the repository

You can refer to the GitHub documentation on how to fork and clone repositories.

Quick reference:

git clone https://github.com/<your-username>/ragna.git

Set up development environment and run Ragna

We use Pixi to manage development environments with Ragna.

Ragna has three main development environments: dev-all-py310, dev-all-py311, and dev-all-py312, which use Python 3.10, 3.11, and 3.12, respectively. The environment dev-all is the same as dev-all-py310. The environment dev-all is used as an example in the sections below, but you can use any of the three Python versions you like.

To both install a development environment and run Ragna in a single step, you can run

pixi run -e dev-all ragna deploy

You can verify that a development version of Ragna is correctly installed with

pixi run -e dev-all ragna --version
# Ideal output: ragna <version-number> devXXXX from ...

Testing, formatting, linting, and type checking

Setup pre-commit hooks

To maintain code standards, we use pre-commit hooks that check contributions before they are committed. To install them, run:

pre-commit install --install-hooks

These checks are used to run the code formatter and linter. They are also run in the CI on each pull request.

Testing

You can run Ragna tests with

pixi run -e dev-all test

Formatting & Linting

To run the Ruff code formatter and checker, as well as other useful formatting and linting tools, you can use

pixi run -e dev pre-commit

Type checking

You can check type annotations with Mypy using

pixi run -e dev-all types

or

pixi run -e dev-all mypy

All of the above

To run all the above checks using a single command as they would be run on the CI, you can use

pixi run -e dev-all ci

Contribute documentation

Ragna uses the Diátaxis framework and the Google developer documentation style guide to author documentation, MkDocs to generate the documentation website, and ReadTheDocs to serve the website.

You can contribute to narrative documentation by adding and updating files in the docs directory.

To start a development build of the website that auto-refreshes on new changes, run the following from the project root:

pixi run -e dev-all mkdocs serve

This serves the docs website at http://127.0.0.1:8000.

You must use a dev-all* environment to build the docs.

View, add, or update images

Ragna tracks most image files with git-lfs.

As a first-time user of git-lfs, set it up with:

git lfs install

To pull all image files to your local repository, run:

git lfs pull

All new or updated images will be tracked by git-lfs. To verify the files being tracked, run:

git lfs ls-files

Contribution best practices

  • Before opening new issues, go through the tracker to ensure there aren't any previous issues related to your topic.
  • Write clear and descriptive issues and include all the necessary context like library versions and the complete error traceback.
  • Eagerly communicate if you are interested in contributing to any open issues.
  • To contribute new features and enhancements, open issues to discuss the work before creating a pull request.
  • Make sure to test your pull request locally, and include relevant unit tests and documentation.