roadmap

package
v1.4.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 15, 2026 License: MIT Imports: 5 Imported by: 0

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

View Source 
const FixesFormat = "v1"

FixesFormat is the one format string the fixes form carries.

View Source 
const Format = "v1"

Format is the one format string the roadmap form carries.

Variables

View Source 
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 

func Render(doc *Doc, source string) string

Render returns the ROADMAP.md the document makes: the same bytes for the same document, every time.

func RenderFixes 

func RenderFixes(fx *Fixes, source string) string

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 

func Decode(file string, data []byte) (*Doc, error)

Decode reads one roadmap file and returns it, or every shape problem of the file together in one error.

func (*Doc) GroupCount 

func (doc *Doc) GroupCount() map[string]int

GroupCount returns the number of items under each group id.

type Fix 

type Fix struct {
	ID, Release, Title, Text, Origin, Status string
	Kept                                     []Pair
}

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 Fixes 

type Fixes struct {
	Title, Text string
	Releases    []Release
	Items       []Fix
}

Fixes is a decoded fixes file.

func DecodeFixes 

func DecodeFixes(file string, data []byte) (*Fixes, error)

DecodeFixes reads one fixes file and returns it, or every shape problem of the file together in one error.

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 

type Note struct {
	ID, Release, Title, Text, Date string
	Kept                           []Pair
}

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.

type Pair 

type Pair struct {
	Key, Value string
}

Pair is one field a move carried under :kept: its key and its value, which may be empty (an empty value records that the field was absent).

type Release 

type Release struct {
	ID, Status, Text, Date string
}

Release is one point release.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.