Skip to content

Contributing to GreenRay AIO

Set up

uv sync                       # Python, dependencies and dev tools from uv.lock
uv run pre-commit install     # optional: lint every commit

Before you open a pull request

uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest
uv run greenray validate

CI runs the same checks on Linux and Windows, and builds the documentation site:

uv sync --group docs
uv run mkdocs serve          # preview at http://127.0.0.1:8000

The site's pages live in docs/. The architecture, contributing, security and changelog pages are filled from the root files of the same name, so edit those, not the stubs.

Adding or changing a scenario

  1. Read docs/scenario-format.md.
  2. Put the problem in src/greenray/data/scenarios/<id>.yaml: briefing, objectives, setup, checks and hints. Never put the answer there; the loader and a pre-commit hook reject solution, explanation and edge_cases.
  3. Put the reference solution in src/greenray/data/solutions/scenarios/<id>.yaml.
  4. Add the id to docs/coverage.md under its blueprint topic.
  5. uv run greenray validate must show ok: the scenario starts broken and its solution fixes it.

Adding a command or help page

  • Commands live in src/greenray/commands/ and are registered with @command("name", help="..."). Registering an existing name is an error unless the module passes override=True.
  • Raise CommandError with the real tool's wording for user mistakes. Any other exception is treated as a simulator bug: the shell rolls the cluster back and reports it.
  • Only emit colour when ctx.colorize is true (the output goes straight to a colour terminal).
  • Help pages live in src/greenray/data/help/<command>/; see src/greenray/content/helppages.py. Write original text in the real tool's layout, and list only options the simulator implements.
  • tests/test_strictness.py is a table of invocations the real tools reject, with the wording they use. A new command should add its own rows: a simulator that accepts a wrong command teaches a wrong habit. When a user reports the real tool being stricter than the simulator, the fix starts with a row in that table.

Versioning

GreenRay AIO uses semantic versioning:

  • A merged set of features bumps the minor version (1.0.0 → 1.1.0), a fix bumps the patch version (1.0.0 → 1.0.1), and a change that breaks existing scenario files bumps the major version.
  • In the same pull request, bump version in pyproject.toml and add a section to CHANGELOG.md.
  • To publish, tag vX.Y.Z on main (git tag v1.1.0 && git push origin v1.1.0). The release workflow then builds the package and creates the GitHub Release.

Content rules

  • Original wording only. Do not copy vendor documentation, man pages or exam questions.
  • Never use the simulated cluster's hostnames or scenario ids in help pages or command guides.
  • NVIDIA product names may describe what is being simulated, but GreenRay AIO must never look endorsed by NVIDIA.