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 -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#

We use pre-commit to automatically do code formatting:

# before commiting
pip install pre-commit
pre-commit install
git commit -m 'my commit'  # this will automatically format your code

Running Tests#

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

# Run all tests
pytest -s -v areal/tests/

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