propose

package
v0.1.2 Latest Latest
Warning

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

Go to latest
Published: Aug 30, 2026 License: MIT Imports: 23 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.

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

Functions

func ConfigFor

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

func NewCmdPropose

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

NewCmdPropose builds the `propose` 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 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

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

Options are the command's inputs.

type Prepared

type Prepared struct {
	Request propose.Request

	// Releasable reports whether the commits produce a release at all.
	Releasable bool

	// Held reports a hold in the manifest. 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 version this release would carry.
	Next 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)

Build assembles the proposal from a repository, without touching a forge.

type ProposeOptions

type ProposeOptions struct {
	Repo   string
	Target string
	Branch string
	Remote string

	AuthorName  string
	AuthorEmail string

	DryRun bool
}

ProposeOptions holds the command's flags.

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