publish

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Sep 4, 2026 License: MIT Imports: 8 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")
)

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

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

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

	// TagAlso names directories that receive `<dir>/<root tag>` at the same
	// commit, right after the root tag, in both modes. Spec 0007.
	TagAlso []string

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

	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
	Created bool
}

TagOutcome is one tag this run was asked to cut.

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