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. Not every merged PR needs a release — cut one 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 releases.md. Add an entry at the top of the list with the version, date, and a short summary of what changed.

  3. 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.

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

  5. 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).
    • Copy the summary from releases.md into the release notes.
    • Publish the release.

  6. Archive on Zenodo. If the Zenodo integration is enabled (see Citing this report), publishing the GitHub Release automatically creates a new Zenodo version and mints a 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.

Setting up Zenodo archiving (one-time)

Archiving on Zenodo gives the report a permanent, citable DOI. Do this once, then every GitHub Release is archived automatically.

  1. Sign in to Zenodo with GitHub (the account must have admin access to the repository, or ask an org admin to do this).
  2. Go to your Zenodo profile → GitHub (https://zenodo.org/account/settings/github/).
  3. Find NASA-IMPACT/virtual-stores-feasibility-report in the repository list and flip the toggle On. (If it isn’t listed, click Sync to refresh from GitHub.)
  4. Create a GitHub Release (or re-publish the existing one). Zenodo will detect it, archive the tagged snapshot, and mint a DOI.

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.

After the first archive, copy the concept DOI into the identifiers section of CITATION.cff and add a DOI badge to the README.md. Zenodo’s GitHub integration guide has full details.

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.