= RISC-V Specification Template

This repository serves as a template for creating GitHub repositories within the RISC-V organization for the purpose of developing specifications. It aims to facilitate and standardize the process of specification development.

NOTE: If you are viewing this in a specification repository, kindly update the title for this section and provide an introduction relevant to your repository.

[IMPORTANT]

ARC submissions: Specifications submitted to the Architecture Review Committee (ARC) must follow the conventions in link:ARC_SUBMISSION.md[ARC_SUBMISSION.md] — versioned GitHub tag, PDF named <short>-v<MAJOR>.<MINOR>-<YYYYMMDD>.pdf, and a title page that matches. The Makefile and CI workflows in this template produce ARC-compliant artifacts on every build by default.

Migrating an existing repo? See link:MIGRATION.md[MIGRATION.md] for the step-by-step checklist to bring a downstream fork in line with the current toolchain — both the ARC submission PDF and the Antora site, which share one source tree. See link:ANTORA.md[ANTORA.md] for how that dual build works and why.

== License

This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the link:LICENSE[LICENSE] file.

== Maintainers

The list of maintainers of this specification is maintained in the link:MAINTAINERS.md[MAINTAINERS] file.

== Contributors

The list of contributors to this specification is maintained in the link:modules/ROOT/pages/contributors.adoc[contributors] file.

For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUTING] file.

== Governance

The governance for this project is defined in the link:GOVERNANCE.md[GOVERNANCE] file.

== Repository Setup Checklist

When instantiating a new repository from this template, perform these one-time setup steps:

1. Enable Actions PR Creation: Go to Settings -> Actions -> General -> Scroll to Workflow permissions -> Check Allow GitHub Actions to create and approve pull requests -> Click Save. (Alternatively, configure a repository secret named GHTOKEN with a Personal Access Token).
2. Initialize Submodules: Run git submodule update --init --recursive in your local workspace.
3. Enable GitHub Pages (only if you want the published HTML site): Go to Settings -> Pages -> Build and deployment -> Set Source to GitHub Actions. The publish workflow attempts this automatically, but the RISC-V organization restricts Pages site creation, so the workflow's built-in token cannot do it — a repository admin must do it once by hand. After that, every release publishes without further intervention.

== Building the Document

=== Directory Structure

The following directories are used to organize the contents of this repo:

• modules/: the specification content, in Antora layout — chapter pages in modules/ROOT/pages/, site navigation in modules/ROOT/nav.adoc, and supporting files such as the BibTeX database in modules/ROOT/resources/. This is where you write.
• src/: the PDF assembler (spec-sample.adoc). It is a thin document that include::s the same chapter pages from modules/ROOT/ to produce the ARC submission PDF, so one source tree feeds both the PDF and the HTML site — see link:ANTORA.md[ANTORA.md].
• docs-resources/: resources for all specifications sourced from link:.gitmodules[git submodule]
• scripts/: versioning and publishing helpers. release-info.sh is the single source of version and phase truth for both artifacts; the others stamp the site version, update SPEC_STATE.md, and build the GitHub Pages site.
• tests/: shell tests for those helper scripts
• dependencies/: software dependencies needed to build the specification
• build/: default directory where the build artifacts are generated — the PDF, plus the HTML site under build/site/ (local preview) or build/pages-site/ (GitHub Pages build)

=== Prerequisites

To build the document, you'll need the following tools installed on your system:

• Make
• asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, and asciidoctor-mathematical
• Docker

=== Cloning the Repository

git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git

All in one single line:

git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git && cd docs-spec-template && git submodule update --init --recursive

[IMPORTANT]

Instantiated via GitHub's "Use this template"? GitHub does not populate submodule contents when creating a repository from a template. If docs-resources is empty, run git submodule update --init --recursive in your local workspace. The Makefile will also attempt to auto-initialize submodules on make build.

=== Building the Documentation

To start the build process, run:

cd ./docs-spec-template && make build

The link:Makefile[] script will check the availability of Docker on your system:

• If Docker is available, the documentation will be built inside a Docker container using the image riscvintl/riscv-docs-base-container-image:latest. This ensures a consistent build environment across different systems.
• If Docker is not available, the documentation will be built directly on your system using the installed tools.

The documentation is generated from the AsciiDoctor source files in your project. The primary source file is specified by the HEADER_SOURCE variable in the Makefile.

The build process utilizes several options, including theming and font settings, and generates a PDF document as output.

=== Cleaning up

To clean up the generated files, run:

make clean

=== Previewing the Antora site locally

The chapter sources under modules/ROOT/pages/ also feed the Antora HTML site. To preview it locally (see link:ANTORA.md[ANTORA.md] for the full dual-build details):

[source,shell]

npm install # Antora + the kroki/mathjax preview extensions docker compose up -d kroki # local diagram server (wavedrom/kroki) npm run preview # builds the site into build/site/

[WARNING]

Citations and the bibliography do not render in the local Antora preview. The cite: and bibliography::[] macros are handled by the RISC-V central playbook's ASAM bibliography extension, which is not bundled in this repository. In local preview they appear as raw text; this is expected, not a build error.

To check bibliography output, build with make (the PDF/HTML use the asciidoctor-bibtex toolchain) or view the specification on the central RISC-V documentation site, where the ASAM extension renders them.

[IMPORTANT]

Don't forget site numbering rules. Chapter/section numbering on the published site is applied by the RISC-V central playbook, keyed to the line numbers of the xref entries in modules/ROOT/nav.adoc — not by anything in this repo. When you finalize your chapter structure (or add/remove/reorder pages in nav.adoc), you must add or update the matching entry in the central playbook's numbering_rules, or your spec will render with wrong or missing chapter numbers. See the Section numbering section of link:ANTORA.md[ANTORA.md] for the exact rule and format.

=== Publishing the Antora site to GitHub Pages

Every v* release tag also publishes the specification as an HTML site on this repository's own GitHub Pages site, alongside the release PDF, via .github/workflows/publish-site.yml. The site lands at https://<org>.github.io/<repo>/.

This needs the one-time Enable GitHub Pages step from the <> above. The workflow tries to enable Pages itself, but the RISC-V organization restricts Pages site creation, so its token is refused (Resource not accessible by integration) and a repository admin has to set the source to GitHub Actions once by hand. Everything after that is automatic.

The site version is stamped from the same source as the PDF, so the two always match. A build with no release tag to name it — such as the first manual run in a new repository — publishes under /spec-sample/dev/ rather than a long vX.YY-<sha>-<date> path, which keeps the URL stable and the site navigation readable; the exact commit is still shown on the cover page.

To build exactly what CI publishes, without touching your antora.yml:

[source,shell]

docker compose up -d kroki # local diagram server, as above NO_STAMP=1 ./scripts/build-pages-site.sh # builds the site into build/pages-site/

[NOTE]

This per-repo site is not the canonical RISC-V documentation site. docs.riscv.org is assembled centrally from many spec repositories; this workflow publishes a standalone copy of the same content, which is the primary HTML output for a spec that is not part of the central library. It also currently publishes a single version rather than a version dropdown — see Publishing to GitHub Pages in link:ANTORA.md[ANTORA.md] for why, and what would change that.

== Automated Versioning and Milestones

The repository includes CI automation for specification revision metadata and state transitions.

=== Trigger for automated version bumps

The version bot is triggered manually, by workflow_dispatch on .github/workflows/version-bot.yml. Merging to main does not cut a version; a maintainer decides when to tag one.

=== End-to-end flow

1. A maintainer dispatches .github/workflows/version-bot.yml against main.
2. The bot finds the latest v* tag and creates the next revision tag (vMAJOR.MINOR) for the current main commit.
3. The bot then calls .github/workflows/build-pdf.yml and .github/workflows/publish-site.yml directly, passing the new version.
4. The build uses the tag as :revnumber: and sets :revdate: to the tagged commit's date, so rebuilding a tag reproduces an identical PDF.
5. scripts/release-info.sh derives phase (:phase:), display state (:phase_display:), warning text (:phase_notice:), and :revremark: from the version milestone.
6. The build publishes a GitHub Release with the generated PDF, and opens the site version stamp PR.
7. The site publish deploys the release to GitHub Pages.

[NOTE]

The bot invokes those workflows rather than relying on its tag push to trigger them, and tags with the built-in GITHUB_TOKEN on purpose. GitHub refuses to let GITHUB_TOKEN start a workflow run, which makes the tag push inert -- so the release chain needs no personal access token, and cannot double-fire by triggering push: tags alongside the direct call. A tag pushed by hand still builds and releases through push: tags: v* as before.

Version increment policy:

• Versions are two-digit vMAJOR.MINOR as a fixed-point decimal (v0.6 = 0.60, v1.0 = 1.00). Ordering is decimal, not semver: v0.8 (0.80) is greater than v0.61.
• Normal step: advance the revision by 0.01 (v0.61 -> v0.62).
• Milestone gates (v0.6, v0.8, v0.9, v0.99, v1.0) are cut manually; the bot never auto-advances onto a gate. When a band is exhausted (for example v0.79), a maintainer cuts the next milestone.

=== Milestone boundaries

• v0.6: Developed (revisions v0.61–v0.79)
• v0.8: Stable (revisions v0.81–v0.89)
• v0.9: Frozen (revisions v0.91–v0.98)
• v0.99: Ratification-Ready
• v1.0: Ratified

=== Development builds

Pull requests and pushes to main produce a development build: the PDF and HTML are uploaded as a 30-day workflow artifact, and pushes to main also republish the Antora site under the dev version. Nothing is tagged and nothing is released.

Development builds are versioned v<latest-tag>-<short-sha>, identical to what a local make produces. They deliberately do not claim the next revision number: a preview stamped v0.02 spends a version that has not been cut, so the real v0.02 release would later ship a second, different document under the same name. Any version carrying a -<sha> suffix is refused by every release step.

=== Official vs prerelease policy

Only these exact versions are published as official releases (prerelease=false):

• v0.6
• v0.8
• v0.9
• v0.99
• v1.0

All other versions are published as prereleases (prerelease=true).

=== Milestone PR behavior

When a new tag crosses into a different phase than the previous tag, the bot opens a PR that updates SPEC_STATE.md for maintainer review. This PR is the checkpoint for governance/process updates required by the new phase.

=== Recommended repository secret

Set a GHTOKEN repository secret in every repository created from this template (Settings -> Secrets and variables -> Actions).

GHTOKEN is recommended, not required: the release chain itself (tag -> PDF -> release -> Pages) runs on the built-in GITHUB_TOKEN.

What needs it are the checks on the PRs these workflows open -- the milestone PR and the site version stamp PR. GitHub refuses to let a GITHUB_TOKEN-authored pull request start further workflow runs, so every check on a bot-opened PR -- the PDF build, pre-commit, Vale, and the Antora content-source validation -- is created in the action_required state and waits for a maintainer to press "Approve and run". The PR itself is still correct; only its checks stall.

GHTOKEN may be either:

• A fine-grained personal access token scoped to the repository with Contents: read and write, Pull requests: read and write, and Workflows: read and write. Simplest to set up; tied to one person's account and expires.
• A GitHub App installation token minted per run with actions/create-github-app-token. Preferred for repositories with more than one maintainer, since it is not tied to an individual.

=== Manual builds

workflow_dispatch for .github/workflows/build-pdf.yml is a preview build: it renders the PDF and HTML for the current main and uploads them as a workflow artifact. It takes no inputs, and it neither tags nor releases anything.

Releasing has exactly one entry point, .github/workflows/version-bot.yml. It previously had two -- build-pdf's dispatch could cut its own tag and release, which meant a milestone cut there produced a release with no SPEC_STATE.md transition and no milestone PR, and its auto-next handling re-released the latest tag on every run instead of advancing.

=== Manual version jumps

workflow_dispatch for .github/workflows/version-bot.yml supports forced jumps:

• Set target_phase=Frozen to force the milestone floor (v0.9).
• Set target_phase=Stable to force v0.8, Ratification-Ready to force v0.99, and so on.
• Set release_version (for example v0.9) to force an explicit version; this takes precedence over target_phase.
• Manual jumps must run on main.
• By default, backward jumps are blocked; set allow_non_monotonic=true only when intentionally overriding this safety check.

== Enabling pre-commit checks locally

The repository has some basic commit checks set up with https://pre-commit.com/[pre-commit] that will be enforced by the GitHub CI. To ensure these checks are also run in the local repository while making changes the following can be done:

.Installing pre-commit tool [source,shell]

Do once on your system

pip3 install pre-commit

.Installing pre-commit git hook in repo [source,shell]

Do once in local repo

pre-commit install

Rather than doing the above pre-commit install in every repo that uses it, you can do it https://pre-commit.com/#automatically-enabling-pre-commit-on-repositories[once on your system.]

When enabling additional checks https://pre-commit.com/#plugins[by editing .pre-commit-config.yaml], it is recommended running the newly added check on all files in the repository. This can be done with the following command:

.Running all pre-commit hooks on all files [source,shell]

pre-commit run --all-files