Documentation
¶
Overview ¶
Package roadmap reads docs/roadmap.sexp and renders ROADMAP.md from it.
The roadmap is data: one `(roadmap "v1" ...)` form read through internal/roadmap/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; internal/docs holds the committed ROADMAP.md to what Render makes of the committed sexp, so the page is never written by hand (#4855 deleted the hand-written one).
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") ...)
: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>"]) ...))
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: 512 << 10, MaxDepth: 8, MaxNodes: 512 << 10}
Limits bounds a roadmap read: a file of at most 512 KiB, 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 ¶
type Fix struct {
ID, Release, Title, Text, Origin, Status string
}
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
}
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).
Source Files
Directories