publish

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

Documentation

Overview

Package publish cuts the release a merged Release merge request describes.

The sequence is fixed by go/forge's contract and by spec 0001 D5:

  1. find the merged Release merge request
  2. resolve the commit that ACTUALLY LANDED on the target branch
  3. read the changelog at that commit — which names the version
  4. create the annotated tag there, and push it
  5. release that tag, exactly as `release` would

Steps 4 and 5 are in that order because forge.CreateRelease refuses a tag that does not exist. That refusal is deliberate: given a missing tag a forge creates one from whatever ref it was handed, turning the call into a tagging operation performed with whichever credential is to hand.

Step 5 is release.Releaser, not a copy of it: spec 0005 D6 makes this package resolve, tag and then run the one implementation of release creation, so a tag it made and a tag a person made are released the same way.

Index

Constants

View Source
const ChangelogFile = "CHANGELOG.md"

ChangelogFile is the file a release is described by.

Variables

View Source
var (
	// ErrMissingField reports a required input absent from a [Request].
	ErrMissingField = errors.New("publish: missing required field")

	// ErrNothingMerged reports no merged release merge request on the release
	// branch. Ordinary: `publish` runs after every merge to the target, and
	// most of those are not releases.
	ErrNothingMerged = errors.New("publish: nothing merged to release")

	// ErrChangelogMoved reports a changelog that named one version when it was
	// read and another when the release step read it again: the tag moved
	// under the run.
	ErrChangelogMoved = errors.New("publish: the changelog no longer names the version")

	// ErrNotYetListed reports a release commit at the head of the checkout
	// that the forge's merged merge requests do not account for yet. GitLab
	// starts the pipeline before it lists the merge, so a retry succeeds.
	ErrNotYetListed = errors.New("publish: the forge has not listed the release that landed yet")
)

Functions

func NestedTagName added in v0.4.0

func NestedTagName(dir, rootTag string) string

NestedTagName is the tag a directory receives alongside the root tag: `<dir>/<root tag>`, Go's convention for a nested module and spec 0008's default for a component. One function, so a per-directory shape later is a change in one place.

Types

type AssetPublisher added in v0.2.0

type AssetPublisher interface {
	CreateReleaseWithAssets(
		ctx context.Context, owner, repo string,
		draft forge.ReleaseDraft, assets []forge.ReleaseAssetSource,
	) (forge.Release, error)
	AddReleaseAssetLocation(ctx context.Context, owner, repo, tagName string, asset forge.ReleaseAssetSource) error
}

AssetPublisher is the part of forge.ReleaseAssetPublisher that publish needs.

OPTIONAL, and discovered separately from Publisher. A provider may create releases and still have no way to publish one complete -- treat a failed discovery and forge.ErrNotSupported identically, as the forge contract says.

Satisfied by forge.ReleaseAssetPublisher.

type Outcome

type Outcome struct {
	Version string
	Tag     string
	Commit  string

	// Number is the merged merge request this release came from.
	Number int

	// Tagged is false when the tag was already there on the same commit.
	Tagged bool

	// RootEarlier reports a root changelog whose top section names a tag that
	// exists at another commit: a component-only release landed and the root
	// did not (spec 0011 D1). Nothing about the root was touched. RootAbsent
	// reports no root changelog at all, which a repository with components
	// may have before its root's first release.
	RootEarlier bool
	RootAbsent  bool

	// AlsoTagged is one entry per directory in Request.TagAlso, in order,
	// naming the tag and whether this run created it. A list of named
	// outcomes rather than a count, so spec 0008 can report a component's tag
	// in the same shape. Spec 0007 D4.
	AlsoTagged []TagOutcome

	// Released is false when the release already existed, or when the forge
	// has no release object.
	Released bool

	// ReleasesUnsupported reports a forge with no release object — a permanent
	// answer about the platform, not a failure.
	ReleasesUnsupported bool

	// TagOnly reports that this run stopped after tagging, by request.
	TagOnly bool

	// AssetsPublished is how many assets the release was created carrying.
	AssetsPublished int

	// AssetsUnsupported reports a forge that cannot publish a release complete,
	// so the release was created and the assets were not attached here.
	AssetsUnsupported bool

	// AssetsAttached is how many assets a re-run added to a release that
	// already existed, and AssetsExtra names what the release carries beyond
	// the manifest. Spec 0006.
	AssetsAttached int
	AssetsExtra    []string

	// SkippedHeadings are level-two headings in the changelog that are not
	// releases, passed over to find the one that is.
	//
	// Reported rather than swallowed. Reading past them is what keeps an
	// unparseable changelog from making a repository permanently unreleasable,
	// but a changelog drifting from the shape colophon writes should be VISIBLE
	// in the job log rather than silently tolerated.
	SkippedHeadings []string

	// DraftFinished reports a release this run published rather than created:
	// a draft an interrupted run left behind. Spec 0014 D3.
	DraftFinished bool

	// NotHonoured names what the forge could not apply. GitLab models neither
	// draft nor prerelease, and reports that rather than staying silent.
	NotHonoured string
}

Outcome reports what happened. Every field is what it DID, not what it intended: a re-run reports false for work a previous run already completed.

type Publisher

type Publisher interface {
	CreateRelease(ctx context.Context, owner, repo string, draft forge.ReleaseDraft) (forge.Release, error)
}

Publisher creates the release object.

OPTIONAL, and nil is a legitimate value: Bitbucket Cloud has no release object at all, so on that platform colophon tags and stops. The tag is the part that matters; the platform genuinely has nowhere to put the rest.

Satisfied by forge.ReleasePublisher.

type ReleaseStatus added in v0.5.0

type ReleaseStatus string

ReleaseStatus is what a run did about a tag's release object.

const (
	// ReleaseNone: the tag carries no release object by design (a tag_also
	// directory or a shared component), or the run was --tag-only.
	ReleaseNone ReleaseStatus = ""
	// ReleaseCreated: this run created it.
	ReleaseCreated ReleaseStatus = "created"
	// ReleasePresent: it already existed.
	ReleasePresent ReleaseStatus = "already present"
)

type Releaser

type Releaser struct {
	// contains filtered or unexported fields
}

Releaser orchestrates the release.

func New

func New(resolver Resolver, tagger Tagger, publisher Publisher) *Releaser

New returns a Releaser. publisher may be nil for a forge with no releases.

func (*Releaser) Do

func (r *Releaser) Do(ctx context.Context, req Request) (Outcome, error)

Do cuts the release.

func (*Releaser) WithAssets added in v0.2.0

func (r *Releaser) WithAssets(a AssetPublisher) *Releaser

WithAssets returns a Releaser that can publish a release complete.

Separate from New because the capability is optional and discovered separately: a nil assets publisher is a fact about the platform, not a failure, and the release is then created without them.

func (*Releaser) WithDrafts added in v0.9.0

func (r *Releaser) WithDrafts(d release.DraftPublisher) *Releaser

WithDrafts returns a Releaser whose release step finishes a draft an interrupted run left behind, before it creates anything. Spec 0014 D4: the step lives in release.Releaser, and this hands it the capability.

func (*Releaser) WithNotes added in v0.3.0

func (r *Releaser) WithNotes(n release.Notes) *Releaser

WithNotes returns a Releaser whose release step can render notes from history should the changelog at the tagged commit not name the version.

On this path that is a race, not a plan: the version came from that very file. Without one the release step refuses rather than guesses.

func (*Releaser) WithReader added in v0.4.0

func (r *Releaser) WithReader(rd release.Reader) *Releaser

WithReader returns a Releaser whose release step can finish a release that already exists by attaching what it lacks. Spec 0006 D5.

type Request

type Request struct {
	// Assets are the artefacts the release should carry, already uploaded, each
	// named by where its bytes live.
	//
	// When these are present the release is created WITH them, in one operation,
	// so no observer sees it without them. When they are empty the release is
	// created as it always was.
	Assets []forge.ReleaseAssetSource

	// TagOnly stops after the tag, creating no release.
	//
	// It exists so the release can be created LATER, on the tag pipeline, once
	// the artefacts a release should carry actually exist. Publishing the
	// release here and attaching assets afterwards is what leaves a release
	// visible and empty, and a consumer fetching an asset in that window gets a
	// 404 that reads as a missing file rather than a race.
	//
	// The tag still has to be cut here, on the default branch: it is what fires
	// the tag pipeline, and forge.CreateRelease refuses a tag that does not
	// already exist.
	TagOnly bool

	Owner string
	Repo  string

	// Remote is the clone location, and Target the branch the release landed
	// on. Branch is the release branch whose merge request is being published.
	Remote string
	Target string
	Branch string

	// HeadRelease is the checkout's head when that is a release commit, and
	// empty otherwise. When set, the merge request the forge names must have
	// landed as this commit.
	HeadRelease string

	Author tree.Author
}

Request is one release.

type Resolver

type Resolver interface {
	FindLastMerged(ctx context.Context, owner, repo, sourceBranch string) (forge.PullRequest, error)
	ResolveMergedCommit(ctx context.Context, owner, repo string, number int) (string, error)
}

Resolver is what `publish` needs to learn what landed, and nothing more. It cannot open, update or close anything.

Satisfied by forge.PullRequests.

type TagOutcome added in v0.4.0

type TagOutcome struct {
	Name    string
	Tag     TagStatus
	Release ReleaseStatus
}

TagOutcome is one tag this run was asked to cut, and the release object it carries, if any (spec 0011 D2).

func (TagOutcome) Created added in v0.4.0

func (t TagOutcome) Created() bool

Created reports whether this run cut the tag. Kept for callers that ask only that.

type TagStatus added in v0.5.0

type TagStatus string

TagStatus is what a run found when it went to cut a tag.

const (
	// TagCreated: this run cut it.
	TagCreated TagStatus = "created"
	// TagPresent: it was already at this commit; a re-run found its own work.
	TagPresent TagStatus = "already present"
	// TagEarlier: it exists at another commit, so the changelog that named it
	// records an earlier release and this run leaves it alone (spec 0011 D1).
	TagEarlier TagStatus = "earlier release"
)

type Tagger

type Tagger interface {
	Tag(ctx context.Context, spec tree.TagSpec) (tree.TagResult, error)
	FileAt(ctx context.Context, req tree.FileRequest) ([]byte, error)
	ResolveTag(ctx context.Context, req tree.TagLookup) (string, error)
	Contains(ctx context.Context, req tree.ContainsRequest) (bool, error)
}

Tagger writes the tag and reads the repository, here and for the release step this package hands the tag to. Satisfied by tree.Recutter.

Jump to

Keyboard shortcuts

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