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 ARC_SUBMISSION.md — versioned GitHub tag, PDF named Migrating an existing repo? See 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 ANTORA.md for how that dual build works and why. |
This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the LICENSE file.
The list of maintainers of this specification is maintained in the MAINTAINERS file.
The list of contributors to this specification is maintained in the contributors file.
For guidelines on how to contribute, refer to the CONTRIBUTING file.
The governance for this project is defined in the GOVERNANCE file.
Community information, including meeting (if held) and mailing lists are detailed in this file.
The following directories are used to organize the contents of this repo:
-
dependencies/: software dependencies needed to build the specification -
docs-resources/: resources for all specifications sourced from git submodule -
src/: source files for the specification -
build/: default directory where the build artifacts are generated
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
git clone --recurse-submodules https://github.com/riscv/docs-spec-template.gitAll in one single line:
git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git && cd docs-spec-template && git submodule update --init --recursiveTo start the build process, run:
cd ./docs-spec-template && make buildThe 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.
The chapter sources under modules/ROOT/pages/ also feed the Antora HTML site. To preview it locally (see ANTORA.md for the full dual-build details):
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 To check bibliography output, build with |
|
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 |
The repository includes CI automation for specification revision metadata and state transitions.
The version bot runs on pushes to main only when files under src/** change (the main specification content).
-
A commit that changes
src/**is pushed tomain. -
.github/workflows/version-bot.ymlfinds the latestv*tag and creates the next revision tag (vMAJOR.MINOR) for that commit. -
The new tag triggers
.github/workflows/build-pdf.yml. -
The build uses the tag as
:revnumber:and sets:revdate:to the build date. -
scripts/release-info.shderives phase (:phase:), display state (:phase_display:), warning text (:phase_notice:), and:revremark:from the version milestone. -
Tag-triggered builds publish GitHub Releases with the generated PDF artifacts.
Version increment policy:
-
Versions are two-digit
vMAJOR.MINORas a fixed-point decimal (v0.6= 0.60,v1.0= 1.00). Ordering is decimal, not semver:v0.8(0.80) is greater thanv0.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 examplev0.79), a maintainer cuts the next milestone.
-
v0.6:Developed(revisionsv0.61–v0.79) -
v0.8:Stable(revisionsv0.81–v0.89) -
v0.9:Frozen(revisionsv0.91–v0.98) -
v0.99:Ratification-Ready -
v1.0:Ratified
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).
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.
workflow_dispatch for .github/workflows/build-pdf.yml supports:
-
release_versionto force an explicit version. -
target_phaseto force a milestone floor (Developed→v0.6,Stable→v0.8, and so on). -
With
target_phase=auto-next(default), manual runs use the latest existing tag if that tag is between milestone floors; otherwise they compute the next revision.
workflow_dispatch for .github/workflows/version-bot.yml supports forced jumps:
-
Set
target_phase=Frozento force the milestone floor (v0.9). -
Set
target_phase=Stableto forcev0.8,Ratification-Readyto forcev0.99, and so on. -
Set
release_version(for examplev0.9) to force an explicit version; this takes precedence overtarget_phase. -
Manual jumps must run on
main. -
By default, backward jumps are blocked; set
allow_non_monotonic=trueonly when intentionally overriding this safety check.
The repository has some basic commit checks set up with 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:
# Do once on your system
pip3 install pre-commit# Do once in local repo
pre-commit installRather than doing the above pre-commit install in every repo that uses it, you can do it once on your system.
When enabling additional checks 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:
pre-commit run --all-files