Documentation
¶
Overview ¶
Package roadmap reads docs/roadmap.sexp and renders ROADMAP.md from it.
The roadmap is data: one `(roadmap "v1" ...)` form read through pkg/sexp (nothing is evaluated), decoded here into typed records, and refused whole, every problem named, when a record is not exactly the shape below. tools/roadmap writes the rendered page; each repository that keeps one holds its committed ROADMAP.md to what Render makes of its committed sexp (here internal/docs), so the page is never written by hand (#4855 deleted the hand-written one). It is the one copy of the roadmap code: nova-sprint's roadmapdoc package was a renamed fork of it, and imports this package instead.
The shape:
(roadmap "v1"
:title "<page title>"
:text "<the page's opening paragraph>"
:scheduled ((scheduled "<id>" :release "<vX.Y>" :title "..." :text "..." :date "YYYY-MM-DD") ...)
:done ((done "<id>" :title "..." :text "..." :date "YYYY-MM-DD" [:kept (...)]) ...)
:groups ((group "<id>" :title "..." :text "...") ...)
:items ((item "<id>" :group "<group id>" :title "..." :text "..." :date "YYYY-MM-DD"
[:why "..."] [:area "..."] [:exists "..."] [:cards <n>]
[:origin "<where it came from: issue #n, PR #n, a card>"] [:release "<target release>"]
[:kept (:<key> "<value>" ...)]) ...))
:kept holds the fields a move between docs/roadmap.sexp and docs/fixes.sexp carried that have no meaning where the record now is (an item's :why on a fix, a fix's :status on an item), each under a key naming where it came from (item-why, fix-status), so a move never drops one and a move back restores it. It is data for nova-work roadmap (nova-sprint's roadmap editor) and is not rendered.
Text values may be wrapped across lines in the file; Render joins every run of whitespace into one blank, so the page reads the same however the file is wrapped.
Index ¶
Constants ¶
const FixesFormat = "v1"
FixesFormat is the one format string the fixes form carries.
const Format = "v1"
Format is the one format string the roadmap form carries.
Variables ¶
var Limits = sexp.Limits{MaxBytes: 10 << 20, MaxDepth: 8, MaxNodes: 10 << 20}
Limits bounds a roadmap read: a file of at most 10 MiB (owner 2026-10-15: no practical limit wanted; schema's roadmap passed 1 MiB; still bounded against a hostile file), the shape's depth with room to spare, and at most one atom per byte, so the byte bound is the one that binds.
Functions ¶
func Render ¶
Render returns the ROADMAP.md the document makes: the same bytes for the same document, every time.
func RenderFixes ¶
RenderFixes returns the FIXES.md the file makes: the same bytes for the same file, every time. Releases and their fixes keep the file's order.
Types ¶
type Doc ¶
type Doc struct {
Title string
Text string
Scheduled []Note
Done []Note
Groups []Group
Items []Item
}
Doc is a decoded roadmap.
func Decode ¶
Decode reads one roadmap file and returns it, or every shape problem of the file together in one error.
func (*Doc) GroupCount ¶
GroupCount returns the number of items under each group id.
type Fix ¶
Fix is one item of a point release: where it came from (a pull request, a card, a commit or a ledger line) and how far it has got.
type Group ¶
type Group struct {
ID, Title, Text string
}
Group is one heading of the roadmap; every item names the group it sits under.
type Item ¶
type Item struct {
ID, Group, Title, Text, Why, Date string
Area, Exists string
Cards int
// Origin names where the item came from (an issue, a pull request, a card
// moved out of the sprint); Release is the release it is aimed at, when one is.
Origin, Release string
Kept []Pair
}
Item is one piece of work after the last scheduled release. Exists says what of it the code already has, so the item covers only the gap; Cards is how many open sprint cards the item replaces (each card is mapped to the item's id in the sprint's own record: card ids carry friend names, which a living file of this repository never does, docs/SPEC-CI.md#generality-text).
type Note ¶
Note is one record of work that is not on the roadmap: scheduled into a named release, or already done. Release is empty for a done note.
Source Files