Contributing

We welcome PRs to this repo from anyone. If you open a PR with new or revised content, please add yourself to the authors list in index.qmd.

Once a PR is approved, the PR author should merge it.

This site uses Quarto to generate website pages using markdown and jupyter notebooks.

Adding pages

To add a new page:

  1. Create new .qmd or .ipynb file
  2. Add the new page to the sidebar section in _quarto.yml so it shows up in the sidebar navigation

Previews

To preview changes, you can run this site locally (see instructions to setup quarto locally below) or use the automated preview generation when opening a PR (see the PR preview workflow).

Release Process

Releases mark citable snapshots of the report. The site will be released when there is a meaningful body of new or revised content.

We use calendar versioning (CalVer) in the form YYYY.MM.MICRO — the year and month the release is published, plus a micro segment that increments within a month, starting at 0 (e.g., 2026.04.0). The first release in a given month is .0; a second release that same month is .1, and so on. Keeping all three segments makes every version the same shape, which sorts and parses predictably.

Steps to create a release

  1. Decide on a version number: Use YYYY.MM.MICRO for the current year and month. Set MICRO to 0 for the first release of the month, or the next number up if that month already has a release (e.g., 2026.06.0, then 2026.06.1).

  2. Update CITATION.cff: Set version to the new version and date-released to the publication date (YYYY-MM-DD). After the Zenodo DOI is minted (see below), keep the concept DOI in place — it always resolves to the latest version.

  3. Open and merge a PR with the CITATION.cff updates. The site will be published automatically on merge to main.

  4. Create a GitHub Release. Go to Releases → Draft a new release:

    • Set the tag to match the version (e.g., 2026.06.0), targeting the main branch.
    • Use the version as the title (e.g., 2026.06.0).
    • Use Github to auto-generate release notes.
    • Publish the release.

Publishing the GitHub Release automatically creates a new Zenodo version and mints a version-specific DOI.

Citing this report

This repository includes a CITATION.cff file describing how to cite the report. GitHub renders a “Cite this repository” button from it, and tools like Zenodo read it when archiving.

Zenodo issues two DOIs:

  • A concept DOI that always points to the latest version — use this one in CITATION.cff and for general citation.
  • A version DOI unique to each release.

Local Development

Install Quarto

Install Quarto by downloading the installer for your platform from quarto.org/docs/get-started, or via a package manager:

  • macOS (Homebrew): brew install --cask quarto
  • Linux: Download the .deb or .rpm package from the Quarto website
  • Windows: Download the .msi installer from the Quarto website

Verify the installation with quarto check.

Run quarto commands

To preview the site locally:

quarto preview

This runs quarto preview, which serves the site and reloads on changes.