Documentation
¶
Overview ¶
Package propose implements the `propose` verb: write the release branch and open or update its merge request.
Index ¶
- Constants
- Variables
- func ConfigFor(p *props.Props) forge.Config
- func ForgeFor(flag string, settings manifest.Manifest, origin remote.Remote) (remote.Remote, error)
- func InsecureHTTPAllowed() bool
- func NewCmdPropose(props *props.Props) *setup.Command
- func Publish(ctx context.Context, prepared Prepared, writer Writer, opts ...tree.Option) (propose.Outcome, error)
- func PublishPreparing(ctx context.Context, prepared Prepared, writer Writer, ...) (propose.Outcome, error)
- func PullRequestsFrom(provider forge.Provider) (forge.PullRequests, error)
- func RefuseInsecureOrigin(origin string) error
- func RepoSettings(p *props.Props, forgeName render.Forge, origin string) repo.Settings
- func Report(w io.Writer, prepared Prepared, outcome propose.Outcome) error
- func Run(ctx context.Context, p *props.Props, opts *ProposeOptions, w io.Writer) error
- func RunPropose(ctx context.Context, p *props.Props, opts *ProposeOptions, _ []string) error
- type Carried
- type HeldOut
- type Options
- type Prepared
- type ProposeOptions
- type Writer
Constants ¶
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.
const DefaultTarget = "main"
DefaultTarget is the branch released from when none is named.
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.
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 ¶
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") )
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).
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.
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 ForgeFor ¶ added in v0.5.0
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 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
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 ¶
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 Run ¶
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 ¶
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
// 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.