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

We recommend using conda, but you can use any package and environment manager you prefer. The environment-dev.yml file at the root of the project lists all the required development dependencies.

Create and activate a conda environment:

conda env create --file environment-dev.yml
conda activate ragna-dev

Setup pre-commit hooks (optional)

To maintain code standards, you can install some pre-commit hooks that check your contributions when you commit them:

pre-commit install

These checks are also run in the CI on each pull request.

Contribute code

You install Ragna in editable mode to test your contributions locally as you develop:

pip install --editable '.[all]'

Verify that a development version is installed with:

ragna --version
# Ideal output: ragna <version-number> devXXXX from ...

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:

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.