Documentation
¶
Overview ¶
Package adr manages Architectural Decision Records — markdown files with YAML frontmatter that capture significant design choices, their context, and their consequences.
Index ¶
- Constants
- func EnsureDir(workdir string) (string, error)
- func Filename(id int, title string) string
- func LinkSupersedes(workdir string, newID, oldID int) error
- func NextID(workdir string) (int, error)
- func ParseStatus(s string) (string, error)
- func Slug(title string) string
- func Statuses() []string
- func Template(title string) string
- type ADR
Constants ¶
const ( StatusProposed = "Proposed" StatusAccepted = "Accepted" StatusDeprecated = "Deprecated" StatusSuperseded = "Superseded" StatusRejected = "Rejected" )
Status values an ADR can carry. Free-form strings are also tolerated when reading, but writes funnel through these constants.
const Dir = ".cloop/adr"
Dir is the relative path inside a project where ADR files live.
Variables ¶
This section is empty.
Functions ¶
func LinkSupersedes ¶
LinkSupersedes wires this ADR to mark `oldID` as superseded by `a.ID`, updating both files. If the old ADR cannot be loaded, returns an error.
func ParseStatus ¶
ParseStatus resolves a user-supplied status to its canonical spelling, case-insensitively.
Reads tolerate a free-form status so that a hand-written file still loads, but writes must not invent a sixth value: a typo persisted as "Acepted" is invisible to every status filter and silently drops the record out of the listings an operator relies on. Refusing it here is the only place that can tell the difference between a typo and a deliberate choice.
Types ¶
type ADR ¶
type ADR struct {
ID int // sequential, 1-indexed
Title string // human title
Status string // Proposed/Accepted/Deprecated/Superseded/Rejected
Date time.Time // creation date
Deciders []string
Tags []string
Supersedes []int // ADR IDs this one replaces
SupersededBy []int // ADR IDs that replace this one
Path string // absolute file path
Body string // markdown body (after frontmatter)
}
ADR is one decision record.
func Create ¶
Create writes a brand-new ADR with the given title and optional body. If body is empty, the default template is used. Returns the saved ADR.
func List ¶
List loads all ADRs sorted by ID ascending. Returns an empty slice (not error) if the directory does not exist.
func (*ADR) Save ¶
Save writes the ADR back to its file. If Path is empty, the caller must set it before calling.
The write is atomic: data is staged in a sibling .tmp file, fsynced, chmod'd, then renamed into place. Without this, a crash mid-write — or two writers racing on a Status update (e.g. one process accepting, another deprecating) — would leave the markdown frontmatter half-written and unparseable, which would silently drop the ADR from listings on the next read.
Source Files