Contribution Guide

Contribution Guide#

Thank you for your interest in contributing to AReaL! We welcome contributions from everyone, whether you’re fixing bugs, improving documentation, or adding new system and algorithmic features.

Setting Up Your Development Environment#

New contributors do not have write permissions to the official repository. Please fork the repository and clone your fork locally. AReaL is fully Python-based, making installation straightforward.

git clone https://github.com/${your-username}/AReaL
cd AReaL
pip3 install -r requirements.txt
pip3 install -e .

Issue Guidelines#

Issue Templates#

Please follow the issue template on GitHub. Issues can be:

  • Bug reports

  • Feature requests

  • Refactor requests

The required fields in the template help reduce communication overhead when resolving issues. Issues with arbitrary formatting may be ignored.

Pull Request Guidelines#

There are no specific PR templates, but pull requests should be related to a well-templated issue. Your PR should:

  • Explain how the issue is resolved

  • Describe the benefits this change will provide

  • Reference the related issue number

Code Quality#

Code Formatting#

Please format your code before opening a PR:

isort . && black .

Running Tests#

AReaL’s unit tests are based on the pytest framework:

# Run all tests (excluding GPU tests)
pytest -m "not gpu"

# Run a specific test case
pytest tests/test_something.py

Note: Running all tests may take several hours to complete.

Documentation#

Writing documentation is an excellent starting point for new contributors. The documentation is located in the docs folder and built using Jupyter Book.

Adding New Documentation#

  1. Create your documentation files in the docs folder

  2. Add the file path to docs/_toc.yaml

  3. Build the documentation:

jb build docs

  1. Preview your changes by opening the HTML files in docs/_build/html

This process allows you to see how your documentation will appear before submitting your contribution.

Contents