Contributing to GRiD#
Open an issue to discuss substantial changes, then submit a focused pull request with the motivation, implementation and validation results. Be considerate and respectful in discussions and reviews.
Branches and receipts#
GRiD has three stages, and each may be ahead of the next. dev collects
reviewed pull requests. main moves when a maintainer merges dev after
running the GPU suite on the primary GPU. PyPI moves when a maintainer tags
main with a fresh full receipt.
Open pull requests against dev. A pull request into dev needs the CPU
lane, the packaging jobs and the docs build to pass. It needs no GPU and no
receipt; the receipt job runs only for main. If you have a GPU, run the
tests that cover your change and report the GPU and the result in the pull
request.
Before main moves, a maintainer runs the stale-shard refresh, which
re-runs the shards whose inputs changed and carries the others, and commits
the refreshed gpu-proof.json. A release is stricter: one fresh full pass
with no carried shards. Receipts recorded on other GPU architectures live
under receipts/ and attest the commit they were recorded at; the
compatibility page lists the latest receipt for each architecture. The release
playbook, RELEASING.md, has the details.
Code and tests#
Follow the surrounding Python and CUDA style. Use descriptive names and document public inputs, output shapes and conventions.
Add regression tests for fixes and numerical checks for new algorithms. See CUDA Validation And Performance Reporting for the CPU and GPU suites.
Do not weaken tolerances or remove failing cases to make tests pass.
For a new algorithm, follow Adding a New Algorithm. Generated wrapper regions must be regenerated from their specifications, not edited by hand.
Change peer libraries in their own repositories, then update GRiD’s submodule pins to commits available from those remotes.
Documentation#
Update the relevant guide and API documentation when behavior changes. Use runnable examples and state limitations alongside the affected feature. Documentation and website edits are outside the receipt fingerprint, so they never require a GPU run.
The site is Sphinx (pydata_sphinx_theme) under docs/source/ plus the
cover page under docs/landing/:
Homepage text and first-screen navigation:
docs/source/index.rst.Install, examples, CUDA status, validation and benchmark pages:
docs/source/user_guide/; API landing text:docs/source/api_reference/index.rst.Add a new page to the nearest
.. toctree::so Sphinx includes it. When a page moves or is merged, add its old path toLEGACY_ROUTESindocs/build_site.pyso published links keep working.The navigation logo is
docs/source/_static/a2r_lab.png(configured indocs/source/conf.py); theme assets such as the favicon andcustom.csslive underdocs/source/_static/. Put figures next to the page that uses them or under_static.
Build exactly what the GitHub Pages workflow (.github/workflows/gh-pages.yml)
builds, from the repository root; developer installs already include the
documentation dependencies (docs/requirements.txt):
.venv/bin/python -m unittest discover -s docs -p 'test_site.py'
.venv/bin/python -m sphinx -b html -W --keep-going docs/source docs/build/html
.venv/bin/python docs/build_site.py # cover + /docs + legacy redirects -> docs/build/site
.venv/bin/python docs/check_site.py docs/build/site
.venv/bin/python -m http.server -d docs/build/site 8000 # preview at http://localhost:8000
Keep the strict build warning-free; the workflow treats warnings as errors.
Writing style#
Write documentation the way the GRiD, MPCGPU and GATO papers are written.
Use plain declarative sentences of one idea each, “we” for what the project
does and the imperative for instructions. State a claim once, with its number,
and put caveats in their own sentences. Use one name per thing throughout.
Avoid em-dashes, arrows in prose, capitalised emphasis, bold lead-ins, emoji,
exclamation marks, rhetorical questions and filler such as “simply”, “note
that” or “importantly”. Describe current behaviour as fact; dates, decision
records and the history of a change belong in the changelog or in
docs/design_history/.
License#
GRiD software contributions are licensed under the repository’s MIT license. The landing-page design attribution and its CC BY-SA 4.0 terms are recorded in the website footer.