propose

package
v0.16.0 Latest Latest
Warning

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

Go to latest
Published: Oct 7, 2026 License: MIT Imports: 27 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.

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")
)

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 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 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 RepoSettings

func RepoSettings(p *props.Props, forgeName render.Forge) 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.

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.
	Forge render.Forge
	Host  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