plan

package
v0.21.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func FormatFrom

func FormatFrom(p *props.Props) output.Format

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 NewCmdPlan

func NewCmdPlan(props *props.Props) *setup.Command

func Render

func Render(w io.Writer, format output.Format, plan Plan) error

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.

func Run added in v0.11.0

func Run(_ context.Context, p *props.Props, opts *PlanOptions, w io.Writer, _ []string) error

Run is RunPlan with its output injected.

Every other verb has one, and plan did not: it rendered to os.Stdout from its handler, which made it the only verb the feature suite could not drive and so the only one whose output nothing described (spec 0020 D4).

func RunPlan

func RunPlan(ctx context.Context, p *props.Props, opts *PlanOptions, args []string) error

RunPlan computes the release the current commits would produce, and prints it. It writes nothing: no branch, no merge request, no tag.

Types

type ComponentPlan added in v0.5.0

type ComponentPlan struct {
	Dir string `json:"dir" yaml:"dir"`

	Plan `yaml:",inline"`
}

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

func Compute(repoPath string) (Plan, error)

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

func (p Plan) HasReleased() bool

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL