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:
- find the merged Release merge request
- resolve the commit that ACTUALLY LANDED on the target branch
- read the changelog at that commit — which names the version
- create the annotated tag there, and push it
- 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
- Variables
- func NestedTagName(dir, rootTag string) string
- type AssetPublisher
- type Outcome
- type Publisher
- type ReleaseStatus
- type Releaser
- func (r *Releaser) Do(ctx context.Context, req Request) (Outcome, error)
- func (r *Releaser) WithAssets(a AssetPublisher) *Releaser
- func (r *Releaser) WithDrafts(d release.DraftPublisher) *Releaser
- func (r *Releaser) WithNotes(n release.Notes) *Releaser
- func (r *Releaser) WithReader(rd release.Reader) *Releaser
- type Request
- type Resolver
- type TagOutcome
- type TagStatus
- type Tagger
Constants ¶
const ChangelogFile = "CHANGELOG.md"
ChangelogFile is the file a release is described by.
Variables ¶
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
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 (*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
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.
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.