propose

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: 31 Imported by: 0

Documentation

Overview

Package propose implements the `propose` verb: write the release branch and open or update its merge request.

Index

Constants

View Source
const ChangelogFile = "CHANGELOG.md"

ChangelogFile is the file a release writes. Not configurable: every project in this estate calls it this, and a configurable name is a way for two projects to disagree about where their history lives.

View Source
const DefaultTarget = "main"

DefaultTarget is the branch released from when none is named.

View Source
const ForgeHint = "set forge: in .colophon.yaml, or pass --forge, as gitlab, github or gitea"

ForgeHint tells the reader of an unknown-host refusal how to name the forge.

View Source
const InsecureHTTPEnv = "COLOPHON_INSECURE_HTTP"

InsecureHTTPEnv opts in to sending the release token over plain http, for a lab forge with no TLS (go/repo spec 0011 D4). It is a safety catch against an http remote, not a boundary: CI config can set it, and whoever edits that can already reach the token. It sits beside the token, not in .colophon.yaml.

Variables

View Source
var (
	// ErrNothingToRelease reports commits that move no version.
	ErrNothingToRelease = errors.New("propose: nothing to release")

	// ErrHeld reports a hold in the manifest.
	ErrHeld = errors.New("propose: releases are held")

	// ErrNoPullRequests reports a forge with no pull-request capability, which
	// on Bitbucket is a permanent answer rather than a failure.
	ErrNoPullRequests = errors.New("propose: this forge does not support merge requests")

	// ErrUnknownForge reports a remote host colophon cannot identify. Guessing
	// would render every changelog link in the wrong shape.
	ErrUnknownForge = errors.New("propose: unrecognised forge host")

	// ErrAlreadyReleased reports that the version about to be proposed has
	// already been released: its release commit is the newest commit `propose`
	// considers unreleased.
	ErrAlreadyReleased = errors.New("propose: that version has already been released")
)
View Source
var DefaultLabels = []string{"release", "colophon"}

DefaultLabels are what a release merge request carries when the manifest names none: what it is, and which tool regenerates it (spec 0029 D1).

View Source
var ErrInsecureOrigin = errors.New("refusing to send the forge token over plain http")

ErrInsecureOrigin reports a forge reached over plain http without the opt-in.

View Source
var LabelDescriptions = map[string]string{
	"release":  "A merge request that cuts a release",
	"colophon": "Opened and regenerated by colophon; edits to its description do not survive",
}

LabelDescriptions are given to the default labels when colophon creates them (spec 0029 D9).

Functions

func ConfigFor

func ConfigFor(p *props.Props) forge.Config

func ForgeFor added in v0.5.0

func ForgeFor(flag string, settings manifest.Manifest, origin remote.Remote) (remote.Remote, error)

ForgeFor applies the forge a repository named, from the flag and the manifest, to the remote its host was parsed from. Spec 0009 D3 and D8: the flag and the key must agree when both are given, and either must agree with a host colophon already knows.

func InsecureHTTPAllowed added in v0.21.3

func InsecureHTTPAllowed() bool

InsecureHTTPAllowed reports whether the operator set InsecureHTTPEnv to true.

func NewCmdPropose

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

func Publish

func Publish(
	ctx context.Context,
	prepared Prepared,
	writer Writer,
	opts ...tree.Option,
) (propose.Outcome, error)

Publish acts on a prepared proposal.

func PublishPreparing added in v0.19.0

func PublishPreparing(
	ctx context.Context,
	prepared Prepared,
	writer Writer,
	preparer propose.LabelPreparer,
	opts ...tree.Option,
) (propose.Outcome, error)

PublishPreparing is Publish offering, through the preparer, to create any missing label before the merge request is opened (spec 0029 D9). A nil preparer only reports them.

func PullRequestsFrom

func PullRequestsFrom(provider forge.Provider) (forge.PullRequests, error)

PullRequestsFrom discovers the pull-request capability on a provider.

A provider that does not implement it and one that returns ErrNotSupported are the same answer, per forge's contract, and both mean colophon cannot propose on that forge rather than that something went wrong.

func RefuseInsecureOrigin added in v0.21.3

func RefuseInsecureOrigin(origin string) error

RefuseInsecureOrigin stops a command before anything connects. Refusing only the git push would be too late: the forge's API client holds the same token and is built first, and go/repo's refusal does not reach it.

func RepoSettings

func RepoSettings(p *props.Props, forgeName render.Forge, origin string) repo.Settings

RepoSettings gives the clone and the push the same credentials the forge calls use.

Forge is not decoration. go/repo derives BOTH the credential environment variable and the git basic-auth username from it — GITLAB_TOKEN and "oauth2" for GitLab, GITHUB_TOKEN and "x-access-token" otherwise — so leaving it unset makes every push use GitHub's convention. Pushing a release branch to GitLab would then read the wrong variable and authenticate as the wrong user.

Token is not optional either, and its absence is the quietest of the three to get wrong. go/repo does NOT read <FORGE>_TOKEN from the environment: Settings.Token is a TokenSource the CALLER supplies, and an unset one resolves to the empty string. That variable name appears only in the HINT text of the error that follows, which reads exactly as though the lookup was attempted and found nothing.

Without it every push is unauthenticated and fails with "no GITLAB token available for private repository". colophon's own integration tests did not catch that, because they built their own repo.Settings with repo.StaticToken — verifying a path production never takes. The cicd component's self-test caught it.

Private is set because a release push always needs a credential, whatever the repository's visibility. The field decides one thing in go/repo: whether a missing token fails fast with a hint, or is treated as an unauthenticated attempt. Failing fast is right here — the alternative surfaces as a rejected push, which reads as a permissions problem rather than an absent token.

Origin is what lets a self-hosted forge receive its own token at all.

func Report added in v0.18.0

func Report(w io.Writer, prepared Prepared, outcome propose.Outcome) error

Report prints what a proposal did, as the command does.

func Run

func Run(ctx context.Context, p *props.Props, opts *ProposeOptions, w io.Writer) error

Run is RunPropose with its output injected, so what the command prints can be asserted rather than inspected by eye. The forge is reached only on the path that actually opens a merge request; the reporting paths need nothing.

func RunPropose

func RunPropose(ctx context.Context, p *props.Props, opts *ProposeOptions, _ []string) error

RunPropose is the `propose` verb.

Types

type Carried added in v0.5.0

type Carried struct {
	Dir     string
	Tag     string
	Version string
}

Carried is one tag a request proposes. Dir is empty for the root.

type HeldOut added in v0.5.0

type HeldOut struct {
	Dir    string
	Tag    string
	Reason string
}

HeldOut is one releasable tag a hold kept out of the request.

type Options

type Options struct {
	// Repo is the path to the repository. History walks up from it to find the
	// root, and everything per-repository is read from that root.
	Repo string

	// Target is the branch being released from.
	Target string

	// Branch is the release branch. Empty derives it from Target.
	Branch string

	// Remote names the git remote to read and push to.
	Remote string

	// Forge names the forge when the remote's host does not (spec 0009 D8).
	Forge string

	// Author signs the release commit.
	Author tree.Author
}

Options are the command's inputs.

type Prepared

type Prepared struct {
	Request propose.Request

	// Releasable is false when nothing, root or component, has anything to
	// release.
	Releasable bool

	// Held is true when everything releasable is held, so there is nothing
	// to propose; HoldReason then names why, one hold per line. A held
	// release is still computed: a hold should make the pending release
	// easier to look at, not hide it.
	Held       bool
	HoldReason string

	// Next is the root's next version when the root is releasable, else the
	// first component's.
	Next string

	// Carries names every tag the request proposes, root first; HeldOut
	// names the releasable ones a hold kept out, with their reasons (spec
	// 0010 D4, D7).
	Carries []Carried
	HeldOut []HeldOut

	// Warnings are annotations a commit wrote where colophon cannot read
	// them (spec 0013 D3).
	Warnings []string

	// Forge and Host identify the provider to build. Forge is empty when the
	// remote's host is not recognised, which is a refusal rather than a guess.
	// EndpointHost is the host in the form the provider reads. Origin is the
	// one place the release token may go.
	Forge        render.Forge
	Host         string
	EndpointHost string
	Origin       string
}

Prepared is everything `propose` computed before touching a forge.

It is returned rather than acted on so the decision can be inspected — and tested — without credentials, and so a hold can be reported with the release it is holding rather than as a bare refusal.

func Build

func Build(opts Options) (Prepared, error)

type ProposeOptions

type ProposeOptions struct {
	Repo        string
	Target      string
	Branch      string
	Remote      string
	Forge       string
	AuthorName  string
	AuthorEmail string
	DryRun      bool
}

type Writer

type Writer = propose.Writer

Writer is the forge capability `propose` needs.

Jump to

Keyboard shortcuts

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