Documentation
¶
Overview ¶
Package apply reads what a commit asserted about a forge object and carries it there.
This is the reading half of spec 0012: the `Updates:` trailer, the target it names, and the statement it makes. Applying a statement needs a forge that can write a comment, which go/forge does not expose yet (go/forge#23), so the writing half is a narrow interface here and nothing implements it in this package.
Nothing in here infers anything. A commit says what happened to a forge object or the object is left alone, which is spec 0012 D1 and the reason this package has no history reading of its own.
Index ¶
- Constants
- Variables
- func Failures(results []Result) int
- func Field(content, field string) (string, bool)
- func Problems(results []Result) int
- func SetField(content, field, value string) (string, bool, error)
- type Applier
- type Commit
- type Instruction
- type IssueCommenter
- type Keyword
- type Kind
- type MergeRequestCommenter
- type Request
- type Result
- type Statement
- type Status
- type Target
- type Wikis
Constants ¶
const Trailer = "updates"
Trailer is the key a commit uses to address a forge object. One key for every kind of target, because a trailer block is read by people and a reader should not have to learn a spelling per kind (spec 0012 D2).
Variables ¶
var ( // ErrNoFrontmatter reports a page that opens with no frontmatter block. ErrNoFrontmatter = errors.New("apply: page has no frontmatter") // ErrNoField reports a frontmatter block that does not carry the field a // statement names. The field is not created: a page whose schema does not // have it is a page this statement was not written for (spec 0012 D3). ErrNoField = errors.New("apply: frontmatter has no such field") )
var ErrBadTarget = errors.New("apply: bad target")
ErrBadTarget reports a target this package cannot address.
var ErrNothingToDo = errors.New("apply: no commit in the span asserts anything")
ErrNothingToDo reports a span whose commits asserted nothing. Not an error from Do, which returns no results happily; it exists for a caller that wants to say so.
var ErrUnknownKeyword = errors.New("apply: unknown keyword")
ErrUnknownKeyword reports a statement this package will not act on.
Functions ¶
func Failures ¶ added in v0.11.0
Failures counts the results a caller can do something about: the forge was asked and refused.
Separate from Problems because the two answer different questions. A person reading the log wants to know that something was skipped; a pipeline deciding whether the run succeeded must not, since a forge that cannot carry an instruction would report the same unclearable problem on every merge (spec 0022 D1).
func Field ¶
Field reads one frontmatter field's value, for a report line about a page that is already where the statement wanted it.
func Problems ¶
Problems reports whether any result needs a person's attention, which is what a caller prints a summary line from.
It counts Skipped as well as Failed, so it is the wrong thing to gate on: Skipped is a forge without the capability, which no change to a repository can clear. Failures is what a caller may act on (spec 0022 D1).
func SetField ¶
SetField sets one frontmatter field and returns the page, whether the value changed, and any refusal.
Line-based, deliberately, rather than a YAML round trip: re-serialising would reformat a page a person wrote and reorder what they ordered, and the diff would be the whole file. Only the one line moves.
Types ¶
type Applier ¶
type Applier struct {
// contains filtered or unexported fields
}
Applier carries statements to forge objects.
Each capability is optional and separately absent: a forge with no wiki, or no issue tracker, reports the instructions it cannot carry and applies the rest. That is `forge.As` at the command layer, and a nil field here.
func New ¶
func New(issues IssueCommenter, mrs MergeRequestCommenter, wikis Wikis) *Applier
New builds an Applier. Any of the three may be nil, meaning the forge does not offer it.
func (*Applier) Do ¶
Do applies every instruction and returns one result each, in order.
It returns an error only when it could not start. A refusal against a single target is a result, not an error, because by the time this runs the merge has happened and a red pipeline over an annotation is worse signal than a yellow one (spec 0012 D5).
A comment is posted with the instruction's marker as go/forge's idempotency key, so the provider finds an existing one and returns it rather than posting twice. That guarantee is the provider's and its result is not distinguishable from a fresh post, so a comment reports Applied either way; only a wiki field, which this package reads before writing, can report Unchanged.
type Commit ¶
Commit is the minimum this package needs. Not policy.Commit: nothing here decides a version, and a package that reads prose should not depend on the one that decides releases.
type Instruction ¶
type Instruction struct {
// SHA is the commit that asserted it, which is what the idempotence
// marker names (spec 0012 D4).
SHA string
Target Target
Statement Statement
// Raw is the trailer's value as written, for a report line about a
// trailer this package could not read.
Raw string
// Err is why this trailer will not be applied, or nil. A refusal is
// carried rather than returned, because one unreadable trailer must not
// stop the others (spec 0012 D5).
Err error
}
Instruction is one `Updates:` trailer, resolved.
func Collect ¶
func Collect(commits []Commit) []Instruction
Collect reads every `Updates:` trailer across a span of commits, oldest first as the caller supplies them, and resolves each into an instruction.
Every trailer produces an instruction, including one this package cannot read: a malformed target is a thing a person wrote and meant, so it is reported rather than dropped, which is the difference between a quiet tool and a silent one.
func (Instruction) Key ¶
func (i Instruction) Key() string
Key identifies this assertion to the forge's at-most-once check: the commit that made it and the object it was about, so one commit updating two objects posts to both, and the same commit twice posts once.
func (Instruction) Readable ¶
func (i Instruction) Readable() bool
Readable reports whether this instruction can be applied.
type IssueCommenter ¶
type IssueCommenter interface {
CreateIssueComment(
ctx context.Context, owner, repo string, number int, draft forge.CommentDraft,
) (forge.Comment, error)
}
IssueCommenter posts a comment on an issue. The method set is go/forge's capability of the same name, so a provider satisfies this directly.
type Keyword ¶
type Keyword string
Keyword is what a commit says about a target. A small closed vocabulary rather than free text, because the same statement has to mean something on a tracker object (a comment) and on a wiki page (a field value), and because a word the tool does not know must be refused rather than guessed at (spec 0012 D11).
type Kind ¶
type Kind string
Kind is what sort of forge object a target names.
const ( // Issue is `#123` or `project#123`. Issue Kind = "issue" // MergeRequest is `!45` or `project!45`. A pull request is the same thing // under the other name, as it is throughout colophon. MergeRequest Kind = "merge request" // Wiki is a path to a wiki page, `project/wikis/specs/0079-thing`. Wiki Kind = "wiki page" )
type MergeRequestCommenter ¶
type MergeRequestCommenter interface {
Comment(
ctx context.Context, owner, repo string, number int, draft forge.CommentDraft,
) (forge.Comment, error)
}
MergeRequestCommenter posts a comment on a merge or pull request.
type Request ¶
type Request struct {
// Owner and Repo are the repository the commits are in, and the default
// project for a target that names none (spec 0012 D7).
Owner string
Repo string
Instructions []Instruction
// Message is the commit message a wiki edit is recorded under.
Message string
}
Request is one run of the verb.
type Result ¶
type Result struct {
Instruction Instruction
Status Status
// Detail is the reason, for every status but Applied.
Detail string
}
Result is one instruction's outcome.
type Statement ¶
type Statement struct {
Keyword Keyword
// Text is whatever followed the keyword, verbatim and optional. It is
// shown to a reader on a tracker object and ignored on a wiki page, where
// there is nowhere to put it (spec 0012 D11).
Text string
}
Statement is what a commit said about its target.
func ParseStatement ¶
ParseStatement reads the keyword and the optional text after it.
type Status ¶
type Status string
Status is what became of one instruction.
const ( // Applied: the forge was written to. Applied Status = "applied" // Unchanged: the target already said what the statement says. Only a wiki // field can report this; a comment's at-most-once is the provider's // promise and is not visible to a caller (see the note on Do). Unchanged Status = "unchanged" // Skipped: nothing was attempted, and Detail says why. An unreadable // trailer or a forge that cannot do this. Skipped Status = "skipped" // Failed: it was attempted and the forge refused. Detail says why, and // the run continues (spec 0012 D5). Failed Status = "failed" )
type Target ¶
type Target struct {
Kind Kind
// Project is empty when the trailer named none, which means the
// repository the commit is in (spec 0012 D7).
Project string
// Number identifies an issue or a merge request; Path identifies a wiki
// page. Exactly one is set.
Number int
Path string
}
Target is one forge object a commit named.
func ParseTarget ¶
ParseTarget reads the target at the head of a trailer value.
The project is optional and defaults to the commit's own repository, since a commit finishing a ticket in the same project is the common case and naming it every time is noise. A cross-project target is ordinary in this estate and is why the token matters (spec 0012 D7).