Adopt ARC submission convention: milestone IDs + dated PDF naming#100
Open
rpsene wants to merge 3 commits into
Open
Adopt ARC submission convention: milestone IDs + dated PDF naming#100rpsene wants to merge 3 commits into
rpsene wants to merge 3 commits into
Conversation
Signed-off-by: Rafael Sene <rafael@riscv.org>
Per the ARC notice (2026-05-24), every spec submitted for review must be a
GitHub tag with a PDF named <short>-v<X.Y.Z>-<YYYYMMDD>.pdf and a title page
that matches. This change makes the template produce ARC-compliant artifacts
on every build (local and CI), introduces the six canonical milestone IDs,
and adds the publication band between ratification-ready and ratified.
Toolchain:
* scripts/release-info.sh now returns canonical milestone IDs:
development-complete, stabilized, frozen, ratification-ready, publication,
ratified. The publication band covers v0.99.1..<v1.0.0. revremark is
prefixed with "Milestone: <id>." so asciidoctor-pdf renders the milestone
on the title page automatically.
* Makefile gains SPEC_SHORT, DATE_STAMP, VERSION_NUM, MILESTONE_ID and a new
arc-rename target that renames build/<base>.pdf to
build/<base>-v<X.Y.Z>-<YYYYMMDD>.pdf on every build-docs run.
* .github/workflows/build-pdf.yml exports VERSION/DATE to the build step,
refreshes target_phase to the canonical IDs, and treats v0.99.1 as an
official release.
* .github/workflows/version-bot.yml target_phase enum refreshed to match.
* src/spec-sample.adoc adds milestone_id/spec_short defaults and surfaces
Document Milestone -- Version -- Date in the phase WARNING admonition.
Docs:
* ARC_SUBMISSION.md (new): policy doc with verbatim ARC notice, the
version->milestone mapping, filename/title-page rules, pre-submission
checklist.
* MIGRATION.md (new): 8-step checklist for forks to adopt the new toolchain
without rewriting existing tags.
* README.adoc: IMPORTANT callout points readers at both docs.
Signed-off-by: Rafael Sene <rafael@riscv.org>
macOS Finder writes .DS_Store files into every browsed directory; without this entry they leak into downstream PRs and review noise. Added both top-level and recursive patterns so the rule survives subdirectory drift. Signed-off-by: Rafael Sene <rafael@riscv.org>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements the ARC submission requirements (announced 2026-05-24): every spec submitted for ARC review must be a GitHub tag with a PDF named
<short>-v<X.Y.Z>-<YYYYMMDD>.pdfand a title page that matches.development-complete,stabilized,frozen,ratification-ready,publication,ratified. The version number (v0.6.0/v0.8.0/v0.9.0/v0.99.0/v0.99.1/v1.0.0) encodes the gate.makeand the CI workflow both producebuild/<short>-v<X.Y.Z>-<YYYYMMDD>.pdf.Version v1.0.0, 2026-05-24: Ratified. A new "Document State" preface (page 2) renders the phase notice as aNote:paragraph. No theme/submodule edits required.Commits in this PR
47bb1119b9d83f4ca22e3What changed (file-level)
scripts/release-info.shpublicationband added between rat-ready and ratified;phase_display_for_phaseemits title-case labels for the title page;revremarkis now the display label only.MakefileSPEC_SHORT,DATE_STAMP,VERSION_NUM,MILESTONE_ID.arc-renametarget renamesbuild/<base>.pdf→build/<base>-v<X.Y.Z>-<YYYYMMDD>.pdfon every build..github/workflows/build-pdf.ymltarget_phaseenum uses canonical IDs;v0.99.1recognized as official release;VERSION/DATEexported to the build step..github/workflows/version-bot.ymltarget_phaseenum refreshed to canonical IDs.src/spec-sample.adoc:toc: macro; new[preface] == Document Stateblock with*Note:* {phase_notice};toc::[]after; defaults formilestone_idandspec_short.README.adocARC_SUBMISSION.mdandMIGRATION.md.ARC_SUBMISSION.mdMIGRATION.md.gitignore.DS_Store(top-level + recursive).Document layout (rendered)
RISC-V Example Specification Document (Zexmpl)+ authors +Version vX.Y.Z, YYYY-MM-DD: <Milestone Display>Note: <phase notice>Validation
Built all seven milestone phases locally (Docker container, asciidoctor-pdf 2.3.24):
spec-sample-v0.5.0-20260524.pdfVersion v0.5.0, 2026-05-24: Draft and DevelopmentAssume everything is subject to change...spec-sample-v0.6.0-20260524.pdfVersion v0.6.0, 2026-05-24: Development CompleteAssume everything is subject to change...spec-sample-v0.8.0-20260524.pdfVersion v0.8.0, 2026-05-24: StabilizedChanges may still occur, but they should be limited in scope...spec-sample-v0.9.0-20260524.pdfVersion v0.9.0, 2026-05-24: FrozenChanges are highly unlikely. A high threshold will be applied...spec-sample-v0.99.0-20260524.pdfVersion v0.99.0, 2026-05-24: Ratification-ReadyThe specification is preparing for ratification...spec-sample-v0.99.1-20260524.pdfVersion v0.99.1, 2026-05-24: PublicationThe specification has cleared ratification-ready...spec-sample-v1.0.0-20260524.pdfVersion v1.0.0, 2026-05-24: RatifiedNo changes are allowed. Any necessary or desired modifications...Test plan
ARC_SUBMISSION.mdfor policy accuracy (especially the version→milestone mapping table and the verbatim ARC notice in §0).MIGRATION.mdfor completeness — would a downstream maintainer be able to follow it without asking questions?Create Specification Documentworkflow on this branch withtarget_phase=stabilizedand confirm the resulting Release attaches a singlespec-sample-v0.8.0-<YYYYMMDD>.pdf..DS_Storefiles appear in the diff.Cleanup done before this PR
vtestandvtest_1tags (local + remote). Legitimate template release tags (v1.0.0,v2.0.0,v3.0.0,v4.0.0–v4.0.2,v0.1.0-example,v1.0_rc1) are preserved — they're part of the template's own version history.