publish

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Sep 1, 2026 License: MIT Imports: 7 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. create the release object on that tag

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.

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

Functions

This section is empty.

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

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

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

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

Publisher 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.

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

	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 Tagger

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

Tagger writes the tag and reads the repository at a commit. Satisfied by tree.Recutter.

Jump to

Keyboard shortcuts

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