roadmap

Documentation

Overview

Package roadmap is nova-work's roadmap editor: it edits a repository's own work record, docs/roadmap.sexp and docs/fixes.sexp, and renders ROADMAP.md and FIXES.md from them in the same step, so neither the data nor the pages are edited by hand and no GitHub call is made per entry.

It writes no reader and no renderer of its own. The files are read through nova-tools pkg/sexp (data, never evaluated), whose forms carry their byte offsets, and an edit splices only the bytes of the records it changes, so comments (a removed record's own trailing comment aside), spacing and every other record stay as they were. A move between the files carries every field; one the target shape has no key for is kept under :kept (carry.go). Every edit is decoded again through nova-tools pkg/roadmap (imported as roadmapdoc), the shape the pages are rendered from, before any byte is written; an edit roadmapdoc refuses is refused whole, nothing written. The pages are roadmapdoc.Render and roadmapdoc.RenderFixes of the saved data, the bytes nova-tools' tools/roadmap writes (`make roadmap`, `go tool roadmap`) and TestRoadmapIsGeneratedFromTheSexp (generated_test.go) holds.

An entry's life (tla/RoadmapEntry.tla): a roadmap item under a group is todo; a fix in a point release is open (planned or in-progress); done is a roadmap item on the :done list, or a fix whose status is done or shipped. Done is final, a release whose status is shipped is frozen, every group and release keeps at least one entry, and every entry names a group or release the file declares. A pull across the two files writes the destination first and the source second, so a stop between the writes leaves the id in both files, which Load refuses and Check names, and never in neither.

Index

• Constants
• func Check(dir string) ([]string, error)
• func Render(dir string) ([]string, error)
• func RenderFile(in, out, source string) (kind string, items int, err error)
• type Entry
• type Fix
• type Item
• type Query
• type Set
  • func Load(dir, today string) (*Set, error)
  • func (s *Set) AddFix(fx Fix) error
  • func (s *Set) AddItem(it Item) error
  • func (s *Set) Changed() []string
  • func (s *Set) Entries() []Entry
  • func (s *Set) Find(q Query) []Entry
  • func (s *Set) MarkDone(evidence string, ids ...string) error
  • func (s *Set) Note(text, title string, ids ...string) error
  • func (s *Set) Pages() map[string]string
  • func (s *Set) Pull(toRelease, toGroup string, ids ...string) error
  • func (s *Set) Remove(ids ...string) error
  • func (s *Set) Save() error

Constants

const (
	RoadmapFile = "docs/roadmap.sexp"
	RoadmapPage = "ROADMAP.md"
	FixesFile   = "docs/fixes.sexp"
	FixesPage   = "FIXES.md"
)

The files of a repository's work record, relative to its root.

const (
	Todo       = "todo"        // a roadmap item under a group
	Scheduled  = "scheduled"   // a roadmap :scheduled note: a record, not work
	Done       = "done"        // a roadmap :done note, or a fix whose status is done
	Planned    = "planned"     // a fix not started
	InProgress = "in-progress" // a fix being worked
	Shipped    = "shipped"     // a fix whose release is cut
)

The states an entry has (Entry.State).

Functions

func Check

func Check(dir string) ([]string, error)

Check is every way the work record is not sound: a file that does not decode, an id in both files, a page that differs from what its data renders. Load already refuses the first two, so Check reads the files itself.

func Render

func Render(dir string) ([]string, error)

Render writes the page each file present renders, and names the pages it changed.

func RenderFile

func RenderFile(in, out, source string) (kind string, items int, err error)

RenderFile renders one data file held anywhere (a work record's roadmap kept outside the repository whose page it is) to out: the roadmap or fixes shape, read off the file's head form, through the same renderer. source is the name the page's header gives the data.

Types

type Entry

type Entry struct {
	ID    string `json:"id"`
	File  string `json:"file"`
	Kind  string `json:"kind"`  // item, scheduled, done or fix
	Place string `json:"place"` // the group of an item, the release of a fix or a scheduled note, "" for a done note
	State string `json:"state"`
	Title string `json:"title"`
	Text  string `json:"text,omitempty"`
}

Entry is one record of the work record, as list prints it.

type Fix

type Fix struct {
	ID, Release, Title, Text, Origin, Status string
}

Fix is a new fix (add).

type Item

type Item struct {
	ID, Group, Title, Text, Origin, Why string
}

Item is a new roadmap item (add).

type Query

type Query struct {
	File  string // "roadmap" or "fixes"
	Place string // a group or release id
	State string
	Text  string // a case-insensitive substring of the id, title or text
}

Query selects entries: each non-empty field must match.

type Set

type Set struct {
	Dir string

	Today string
	// contains filtered or unexported fields
}

Set is one repository's work record: the roadmap and the fixes file. Either may be absent; a verb that needs an absent one is refused.

func Load

func Load(dir, today string) (*Set, error)

Load reads the work record under dir and decodes it; a file that does not decode, or an id that stands twice across the two files, is refused with every problem named.

func (*Set) AddFix

func (s *Set) AddFix(fx Fix) error

AddFix adds a fix to its release.

func (*Set) AddItem

func (s *Set) AddItem(it Item) error

AddItem adds a roadmap item under its group.

func (*Set) Changed

func (s *Set) Changed() []string

Changed names the files an edit changed.

func (*Set) Entries

func (s *Set) Entries() []Entry

Entries are every record of both files, the roadmap's first, in file order.

func (*Set) Find

func (s *Set) Find(q Query) []Entry

Find returns the entries q selects.

func (*Set) MarkDone

func (s *Set) MarkDone(evidence string, ids ...string) error

MarkDone marks the entries done with the evidence that they are: a pull request (PR #n or #n), a commit (7 to 40 hex digits) or its GitHub link. A fix's status becomes done; an item moves to the roadmap's :done list, dated today. The evidence is appended to the text.

func (*Set) Note

func (s *Set) Note(text, title string, ids ...string) error

Note appends text to each entry's :text and, with a title, gives it that title; the title it had is kept under :kept (earlier-title), never dropped.

tla/RoadmapEntry.tla Note

func (*Set) Pages

func (s *Set) Pages() map[string]string

Pages renders the page of each file present, from its current data.

func (*Set) Pull

func (s *Set) Pull(toRelease, toGroup string, ids ...string) error

Pull moves the entries to a release (toRelease) or a group (toGroup): an item into a fixes release becomes a fix, planned; a fix onto the roadmap becomes an item; within a file only the :group or :release changes. A move across the files carries every field: one the other file has no key for goes under :kept, and a move back restores it (carry.go).

func (*Set) Remove

func (s *Set) Remove(ids ...string) error

Remove takes the entries out; each must be movable.

func (*Set) Save

func (s *Set) Save() error

Save writes each changed file and its page, each through a temporary file and a rename: the file an entry moved into first, so a stop between the writes leaves the entry in both files (Load refuses it, Check names it), never in neither. Within one file the data is written before its page; a stop between those two leaves the page stale, which Check names and `nova-work roadmap render` mends.

tla/RoadmapEntry.tla Save