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. The main development environment is all-py310, which should be used for most use cases and is used in the sections below.

To install a development environment, run

pixi install --environment all-py310 --frozen

You can then run Ragna with

pixi run --environment all-py310 ragna deploy

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

pixi run --environment all-py310 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 --environment all-py310 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 --environment all-py310 pre-commit

Type checking

You can check type annotations with Mypy using

pixi run --environment all-py310 types

or

pixi run --environment all-py310 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 ---environment all-py310 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 --environment all-py310 mkdocs serve

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

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.