Contribution guide

Contributions to the spec text, examples and schemas are highly welcome and appreciated by the ngff community. If you propose an RFC (i.e., major change) or a a minor change (pull request), please make sure to follow these guidelines.

Major changes should follow the RFC process as it was laid out in RFC1.

Building the documentation¶

Build and inspect changes to the documentation before submitting a PR.

This project uses uv to manage its required (python) tooling, and just to run common development tasks.

Install uv, then set up an environment with the correct python version and development dependencies with

uv sync

This document uses jupyter-book to generate the pages and MyST markdown for formatting. After installing these via the dependencies, navigate into the repository on your machine and build the book using the following command:

just serve

This will build the book and start a local server to inspect the changes in your browser.

To generate the “production” output in the ./_build/ directory, use

just build

To see all available recipes, use

just

Code quality¶

To maximise consistency and minimise non-meaningful git churn, pre-commit hooks are used to lint and format some types of contribution. This is enforced on CI.

When you clone the repository, install the hooks with just pre-commit-install. These will run whenever you make a commit; you can run them manually with just pre-commit.

First contribution¶

If you haven’t contributed to the spec before, please add yourself as an author in the myst.yml metadata file. This should look like this, for example:

    - name: John A. Doe
      id: jdoe
      orcid: xxxx-xxxx-xxxx-xxxx
      github: jdoe

For more information see myst documentation on author formatting.

When you submit your first PR, make sure to rebuild the CITATION.cff file in the root of this repository. To do so, run the following command:

just cff

Make sure the updated CITATION.cff file is included in your PR.

Text format¶

Contributions should conform to Semantic Line Breaks (SemBr), to improve change tracking.

The specification uses MyST extensively for a number of formatting options to make the text readable and improve structure.

Referencing¶

MyST allows a number of ways to reference and cross-reference inside this text and across several of the pages in this repo. For an overview of supported referencing syntax, see the MyST doc pages. It is recommended to use the following syntax in this document for consistency:

anchor: (your-reference-name)=
reference: [This is a reference](#your-reference-name)

For cross-referencing in the spec document, make sure to prepend the reference anchor with versionX like so:

## Some header
(version0.9:some-header)=

Otherwise, the same anchors may not be possible to resolve if multiple versions of the spec document are built and viewed together.

Highlighting¶

If you refer to fields or values that would appear in JSON files, please use backticks to highlight them, like so:

The `multiscales` field contains an array of dictionaries.

You may still use bold, italics or quotation marks for emphasis where appropriate, but please use backticks for JSON fields and values.

Citations¶

ngff-spec relies on sphinxcontrib-bibtex for citations. To add a citation to the text, add it as a bibtex entry in the references.bib file in the root of this repository. You can then cite it in the text using the following syntax:

This is a citation {cite:t}`citation_key`.

where citation_key is the key of the bibtex entry in the references.bib file.

Json examples¶

We suggest using dropdowns for example code and other highlighting. For examples, please use the following syntax to wrap your examples:

:::{dropdown} Example

Some informative text about your example
```json
"key": "value"
```
:::

which results in

"key": "value"

If you want to link in example metadata from somewhere in this repo (i.e, a json file), use this syntax:

:::dropdown Example

Some informative text about your example
```{literalinclude} path/to/example.json
:language: json
:linenos:
:tab-width: 2
```
:::

Other useful admonitions and directives (e.g., hint, note) can be found here.

Release process checklist¶

Before creating a release, please make sure to go through the following items to make sure the release is complete and consistent.

• Update _version.py. Some internal code requires a version number to be provided there to auto-generate some parts of the documentation.
• Update versions in examples. Go through the examples in the examples/ and make sure that all version numbers in the .json files are up-to-date.
• Update the specification number in the spec text. The spec text mentions its own version number in several places. Please make sure to update those to the new version.
• Make sure all tests are passing. Run the test suite to make sure that all tests are passing before creating a release.
• Update the version history. Add a new entry to the version history file with the new version number and date, and a summary of the changes made in this release.