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
- 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 ¶
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") )
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 (*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.