Skip to content

Contributing

Jump to bottom
Animesh Trivedi edited this page Aug 28, 2026 · 1 revision

Contributing

Thanks for your interest in improving Opal. This page covers how to report issues, how to submit pull requests, and the formatting convention the project expects.

Before you start

Set up your environment first — see Install Requirements for the uv/virtual-environment setup. This page assumes you already have a working checkout and can run the simulator.

Before submitting any change, make sure it passes the test suite — see Testing for how to run the tests.

Reporting issues

Open an issue on GitHub. Three issue templates are available to help structure the report:

  • Bug report — describe the bug, steps to reproduce (which config file, exact command line, and the error/crash output), and expected behavior.
  • Feature request — describe the problem you're trying to solve and the solution you'd like.
  • Custom issue template — a free-form template for anything that doesn't fit the other two (problem statement + desired functionality).

If you're unsure whether something is a bug or by design, open an issue anyway — that's the right place to ask.

Submitting a pull request

  1. Fork/branch, make your change.
  2. Format the code (see below).
  3. Run the test suite — see Testing.
  4. Open a pull request against main.

There is no separate PR template; a clear description of what changed and why is sufficient.

Code formatting: Black

The project follows the Black Python formatter as its one required convention. The configuration lives in pyproject.toml:

[tool.black]
line-length = 120
target-version = ["py311"]

Install Black and run the formatter from the top-level directory before sending a pull request:

uv pip install black
sh-black-formatter.sh

sh-black-formatter.sh simply runs black --config ./pyproject.toml --no-cache . over the whole repository, so it reformats every Python file, not just the ones you touched.

Optional: pre-commit hook

The repository ships a git hook at .githooks/pre-commit that runs Black automatically on just the staged .py files at commit time (and re-stages them after formatting). It is not enabled by default — turn it on once per clone with:

git config core.hooksPath .githooks

This is a convenience so you don't forget to format before committing; running sh-black-formatter.sh manually before opening the PR achieves the same result.

Configuration changes

If your change adds or modifies simulation configuration fields, please also update the documentation on Configuration Simulation so the config reference stays in sync with the code.

Contacts / questions

If you have questions or run into issues, open an issue on GitHub and tag @animeshtrivedi and @raduioanstoica.

License

Opal is released under the Apache License 2.0. By contributing, you agree that your contributions will be licensed under the same terms.

Clone this wiki locally