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 the binary writes are the lines the board reads back; docs/traces.md is the spec and 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 the block from holds into body as it is, bytes and all, where PutState would put a new one; a from without a block leaves body as it was. It is what a body rewritten from scratch with traces off does with the block the old body held: no block is written, and the one already there is not dropped.
func PutState ¶
PutState writes s into body: the first block is replaced where it is and any later one removed; a body without one gets the block appended 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, no trailing newline, with V set to StateVersion. It refuses a value ParseState would not read back the same way, or that would break the comment.
func Rewrite ¶
Rewrite is PutState of Merge over the state body already holds: what a step does to a PR body.
func StripState ¶
StripState removes every block from body, each with the line it had to itself and the blank line above it, 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 several commits, so every Step: and Review: line is kept in order; Step and Review are the last of each.
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 now, as the last step that ran left it. Task is the lead's id, Riders the rest of a bundle, After the base task's id. Round, Open and Asks are a review's counts: the round, the findings awaiting a verdict, and the questions waiting on a person outside the run's own turn. 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 step, task, riders and after, and each count from the update where it was passed, else from prev. A prev that was no state is the zero value, so nothing carries.
func ParseState ¶
ParseState reads the first block a body holds. No block, JSON that does not parse, a version other than StateVersion, or a count below zero is no state, never an error: a body nobody controlled is still read. Unknown keys are ignored.
type Trailers ¶
type Trailers struct {
Tasks []string `json:"tasks,omitempty"`
Step string `json:"step,omitempty"`
Review *Review `json:"review,omitempty"`
}
Trailers is what one commit message says about its task and step. Tasks holds every member of a bundle, lead first; Step the step whose work the commit carries; Review the counts on a resolve fix.
Source Files