Documentation
¶
Index ¶
- func FormatFrom(p *props.Props) output.Format
- func NewCmdPlan(props *props.Props) *setup.Command
- func Render(w io.Writer, format output.Format, plan Plan) error
- func Run(_ context.Context, p *props.Props, opts *PlanOptions, w io.Writer, _ []string) error
- func RunPlan(ctx context.Context, p *props.Props, opts *PlanOptions, args []string) error
- type ComponentPlan
- type Fixup
- type Plan
- type PlanOptions
- type Reason
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FormatFrom ¶
FormatFrom reads the root's --output flag, which the framework binds into the config store. An unrecognised or absent value means text, because a plan a person cannot read is worse than one a machine cannot parse.
func Render ¶
Render writes a plan. Exported and taking its writer and format explicitly so it can be tested without a command, a terminal, or a config store.
Text is rendered here rather than through the renderer's text callback, because that callback is func(io.Writer) with no error return: a write failure was recorded and then discarded, so a broken pipe produced a partial plan and a success. Structured formats still go through the renderer, which does report its errors.
Types ¶
type ComponentPlan ¶ added in v0.5.0
ComponentPlan is one component's decision, in the root's shape.
type Fixup ¶ added in v0.21.0
type Fixup struct {
SHA string `json:"sha" yaml:"sha"`
Subject string `json:"subject" yaml:"subject"`
Target string `json:"target,omitempty" yaml:"target,omitempty"`
TargetSubject string `json:"target_subject,omitempty" yaml:"target_subject,omitempty"`
InRange bool `json:"in_range" yaml:"in_range"`
}
Fixup is a fixup commit and what it was tied to. Target is empty when no commit has the subject it names; InRange is false when the target has already been released.
type Plan ¶
type Plan struct {
Repository string `json:"repository,omitempty" yaml:"repository,omitempty"`
// Current is the version the project is at. FromTag is empty when it has
// never released, which Current alone cannot express.
Current string `json:"current" yaml:"current"`
FromTag string `json:"from_tag,omitempty" yaml:"from_tag,omitempty"`
// Next is the version this release would carry. Empty when nothing is due.
Next string `json:"next,omitempty" yaml:"next,omitempty"`
Bump string `json:"bump" yaml:"bump"`
// Releasable is authoritative. Do not infer it from Bump: an honoured
// Release-As trailer can move a version without moving any numeric
// component.
Releasable bool `json:"releasable" yaml:"releasable"`
// Held reports a hold in the manifest. A held release is still computed and
// still shown — a hold should make the pending release easier to look at,
// not hide it.
Held bool `json:"held" yaml:"held"`
HoldReason string `json:"hold_reason,omitempty" yaml:"hold_reason,omitempty"`
Reasons []Reason `json:"reasons,omitempty" yaml:"reasons,omitempty"`
// Notes are the annotations commits contributed through a Release-Note:
// trailer or block (spec 0003). Shown so a maintainer can see what the
// release will SAY, not only what version it will carry — the notes are
// the part a reader acts on.
ReleaseNotes []string `json:"release_notes,omitempty" yaml:"release_notes,omitempty"`
Notes []string `json:"notes,omitempty" yaml:"notes,omitempty"`
// Considered is every unreleased commit, including those that moved
// nothing. A maintainer asking "why is there no release?" is answered by
// this rather than by an empty Reasons list.
Considered int `json:"considered" yaml:"considered"`
// Fixups are the fixup!, squash! and amend! commits considered, each with
// the commit it was tied to (spec 0032 D5). They are among Considered.
Fixups []Fixup `json:"fixups,omitempty" yaml:"fixups,omitempty"`
// Warnings are annotations a commit wrote where colophon cannot read
// them, which decide nothing and would otherwise be silent (spec 0013 D3).
Warnings []string `json:"warnings,omitempty" yaml:"warnings,omitempty"`
// Components are the directories with a version of their own, each
// decided from the commits that touch it, in manifest order (spec 0010
// D3). Absent from a repository without the key, so its output is
// unchanged.
Components []ComponentPlan `json:"components,omitempty" yaml:"components,omitempty"`
// Root is "none" when the root does not release (spec 0027 D5). The
// fields above then describe no release, and Unreleased lists the
// commits outside every component, which release nothing.
Root string `json:"root,omitempty" yaml:"root,omitempty"`
Unreleased []Reason `json:"unreleased,omitempty" yaml:"unreleased,omitempty"`
}
Plan is what `plan` computed. It is the machine-readable form, and it is the reason this command exists as much as the human one: comparing colophon with another release tool means running both and diffing the answers, which needs a shape a diff can read.
func Compute ¶
Compute is the whole of `plan` with no I/O of its own beyond reading the repository, so it is callable and testable without a command.
func (Plan) HasReleased ¶
HasReleased reports whether the project has ever cut a release.
type PlanOptions ¶
type PlanOptions struct {
Repo string
}
type Reason ¶
type Reason struct {
SHA string `json:"sha" yaml:"sha"`
Type string `json:"type" yaml:"type"`
Scope string `json:"scope,omitempty" yaml:"scope,omitempty"`
Subject string `json:"subject" yaml:"subject"`
Bump string `json:"bump" yaml:"bump"`
Why string `json:"why" yaml:"why"`
}
Reason is one commit's contribution.