Documentation
¶
Overview ¶
Package trace is the vocabulary of what f10 leaves on the host for a reader of the history: the git trailers a step's commit carries. Render and Parse sit side by side so the lines written are the lines read back; docs/traces.md is the spec, testdata/trailers its conformance suite.
Index ¶
- Constants
- Variables
- func CarryState(body, from string) string
- func PutState(body string, s State) (string, error)
- func Render(t Trailers) (string, error)
- func RenderState(s State) (string, error)
- func Rewrite(body string, u Update) (string, error)
- func StripState(body string) string
- type Parsed
- type Review
- type State
- type Trailers
- type Update
Constants ¶
const ( KeyTask = "Task" KeyStep = "Step" KeyReview = "Review" )
The three trailer keys, version 1 of the spec.
const StateVersion = 1
StateVersion is the `v` every block written today carries; a block with another version reads as no state.
Variables ¶
var ( // ErrBadCount is a state count below zero. ErrBadCount = errors.New("trace: state counts are zero or more") // ErrBadAfter is a base task id with whitespace in it. ErrBadAfter = errors.New("trace: a base task id has no whitespace") )
var ( // ErrBadStep is a step name outside `[a-z][a-z0-9-]*`. ErrBadStep = errors.New("trace: a step is a lowercase token") // ErrBadTask is a task id with whitespace in it. ErrBadTask = errors.New("trace: a task id has no whitespace") // ErrBadReview is a review count below zero. ErrBadReview = errors.New("trace: review counts are zero or more") )
Functions ¶
func CarryState ¶
CarryState copies from's block into body byte for byte, where PutState would put one, so a body rewritten from scratch with traces off keeps the old block unrewritten.
func PutState ¶
PutState replaces the first block in place and removes any later one, else appends after a blank line; nothing else in the body changes.
func Render ¶
Render writes the trailer lines in fixed order: every Task:, then Step:, then Review:, each newline-terminated. A zero value renders as "". It refuses a value Parse would not read back the same way.
func RenderState ¶
RenderState writes the block for s, one line, V forced to StateVersion. It refuses a value ParseState would not read back the same way.
func StripState ¶
StripState removes every block, for a commit message built from a PR body: the block describes the PR, not the commit.
Types ¶
type Parsed ¶
type Parsed struct {
Trailers
Steps []string `json:"steps,omitempty"`
Reviews []Review `json:"reviews,omitempty"`
}
Parsed is what Parse reads out of a whole message: a squash merge concatenates commits, so every Step: and Review: line is kept in order, Step and Review being the last.
type Review ¶
type Review struct {
Round int `json:"round"`
Fixed int `json:"fixed"`
Skipped int `json:"skipped"`
}
Review is a resolve's fix commit in counts: the round it settled, and how many findings it fixed and skipped.
type State ¶
type State struct {
V int `json:"v"`
Task string `json:"task,omitempty"`
Riders []string `json:"riders,omitempty"`
Step string `json:"step"`
Round int `json:"round,omitempty"`
Open int `json:"open,omitempty"`
Asks int `json:"asks,omitempty"`
After string `json:"after,omitempty"`
}
State is the hidden block a PR body carries: where the task stands, as the last step left it. Round, Open and Asks are a review's counts (findings awaiting a verdict, questions waiting on a person); the JSON key order is the struct's, which is the spec's.
func Merge ¶
Merge is the state a rewrite leaves: the update's fields, and each count from the update where passed, else from prev.
func ParseState ¶
ParseState reads the first block a body holds. Anything unreadable (no block, bad JSON, another version, a count below zero) is no state, never an error: a body nobody controlled is still read.
Source Files