Documentation
¶
Overview ¶
Package release creates the release object for a tag that already exists.
Spec 0005. It starts from the TAG, not from a merge request, so it serves a tag `publish --tag-only` made and one a person made in the same way. The sequence is:
- resolve the tag to its commit on the remote
- refuse unless the target branch contains that commit
- take the notes from the changelog at that commit when it names this version, and render them from history when it does not
- create the release, carrying its assets where the forge can
`publish` runs the same steps after it has tagged, which is what makes this the one implementation of release creation.
Index ¶
- Constants
- Variables
- type AssetPublisher
- type Checkouter
- type DraftPublisher
- type Generator
- type Notes
- type Outcome
- type Publisher
- type Reader
- type ReleaseState
- 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 DraftPublisher) *Releaser
- func (r *Releaser) WithReader(rd Reader) *Releaser
- func (r *Releaser) WithWait(wait func(context.Context, time.Duration) error) *Releaser
- type Request
- type Source
- type Tree
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("release: missing required field") // ErrNotAVersion reports a tag that does not name a semantic version. ErrNotAVersion = errors.New("release: tag is not a version") // ErrNotContained reports a tag whose commit the target branch does not // carry. Spec 0005 D2: there is no flag past this. ErrNotContained = errors.New("release: the target branch does not contain the tagged commit") // ErrNotRootTag reports a tag with a prefix no declared component owns. // Spec 0007 D5; lifted for declared components by spec 0011 D4. ErrNotRootTag = errors.New("release: not a root tag") )
var ErrTagMoved = fmt.Errorf("release: the tag moved between being resolved and being read")
ErrTagMoved reports a tag that points somewhere else than it did when it was resolved a moment ago.
Functions ¶
This section is empty.
Types ¶
type AssetPublisher ¶
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 creates the release WITH its assets, in one operation, and attaches a hosted asset to a release that already exists. OPTIONAL, discovered separately. Satisfied by forge.ReleaseAssetPublisher.
type Checkouter ¶
Checkouter writes a working clone detached at a tag. Satisfied by tree.Recutter.
type DraftPublisher ¶ added in v0.9.0
type DraftPublisher interface {
PublishRelease(ctx context.Context, owner, repo, tagName string) (forge.Release, error)
}
DraftPublisher finishes a release that was created and never published. OPTIONAL, discovered separately: a forge that models no draft implements nothing here, and GitLab is one. Satisfied by forge.DraftPublisher.
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator renders the notes for a release from the commits it covers, the way `propose` would have, for a tag the changelog does not describe.
Spec 0005 D3 and D4. It works from its own clone of the target branch, tags included, so the answer never depends on what a runner's checkout happened to fetch.
func NewGenerator ¶
func NewGenerator(c Checkouter, links render.Links) *Generator
NewGenerator returns a Generator that clones through c and links entries the way links says.
type Notes ¶
Notes renders release notes from the commits a release covers, for a tag the changelog does not describe. Satisfied by Generator.
type Outcome ¶
type Outcome struct {
Version string
Tag string
Commit string
// Dir is the component the tag belongs to, empty for the root.
Dir string
// NoReleaseObject reports a tag that carries none by design: a tag_also
// directory's, or a component's whose `release` is off (spec 0011 D6,
// 0027 D4). For a shared one RootTag names the root's tag, whose release
// covers it. Nothing was created, and nothing was wrong.
NoReleaseObject bool
RootTag string
// Released is false when the release already existed, or the forge has
// no release object.
Released bool
// ReleasesUnsupported reports a forge with no release object.
ReleasesUnsupported 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 without them, or cannot hold a
// location as an asset, so none was attached.
AssetsUnsupported bool
// AssetsAttached is how many assets this run added to a release that
// already existed. Spec 0006 D2: reported apart from AssetsPublished, and
// Released stays false, because this run did not create it.
AssetsAttached int
// AssetsExtra names assets the release carries and the manifest does not.
// Reported and never removed: there is no delete in the contract, and a
// person may have put them there.
AssetsExtra []string
// Generated reports that the notes were rendered from history because the
// changelog at the commit does not describe this version. Spec 0005 D3:
// the release is created, and this is said rather than hidden.
Generated bool
// ChangelogSaid is the version the changelog's newest section named
// instead, when Generated; empty when there was no readable section.
ChangelogSaid string
// SkippedHeadings are level-two headings passed over in the changelog to
// find the release. Reported so drift is visible in a job log.
SkippedHeadings []string
// DraftFinished reports a release this run PUBLISHED rather than created:
// a draft an interrupted run left behind, invisible until now. Spec 0014
// D3. It needs a Reader to be knowable at all; without one the run still
// finishes the draft and simply does not say so.
DraftFinished bool
// NotHonoured names what the forge could not apply.
NotHonoured string
// StandingIncluded names the standing files this release body carries, in
// prefix-then-suffix order (spec 0021).
StandingIncluded []string
// StandingMissing names standing files the manifest names and the tree
// does not carry at the released commit. The release proceeds without
// them and says so, rather than refusing (spec 0021 D6).
StandingMissing []string
}
Outcome reports what happened. Every field is what it DID: a re-run reports false for work a previous run 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: nil means the forge has no release object, and the tag is the release. Satisfied by forge.ReleasePublisher.
type Reader ¶ added in v0.4.0
type Reader interface {
GetReleaseByTag(ctx context.Context, owner, repo, tag string) (forge.Release, error)
}
Reader reads a release that exists. Satisfied by forge.Provider, which every adapter implements; a nil Reader means an existing release is reported as present and not finished. Spec 0006 D5.
type ReleaseState ¶ added in v0.11.0
type ReleaseState int
ReleaseState is what a reader could tell about a tag's release object.
Three answers rather than two, because "there is no release" and "I could not find out" are different facts and only one of them is worth telling anybody about (spec 0018 D4).
const ( // ReleaseUnknown: the read failed. The network being exactly as reliable // as it was the day this spec was written, that is not evidence of // anything and is reported as nothing. ReleaseUnknown ReleaseState = iota // ReleasePresent: the tag carries a release. ReleasePresent // ReleaseAbsent: the tag exists and carries no release object. This is a // release that half-happened. ReleaseAbsent )
func StateOf ¶ added in v0.11.0
func StateOf(ctx context.Context, rd Reader, owner, repo, tag string) ReleaseState
StateOf asks whether a tag carries a release object.
A nil reader answers ReleaseUnknown: a run without one cannot make the distinction, which is the same way spec 0006's asset diffing degrades.
type Releaser ¶
type Releaser struct {
// contains filtered or unexported fields
}
Releaser creates releases.
func (*Releaser) WithAssets ¶
func (r *Releaser) WithAssets(a AssetPublisher) *Releaser
WithAssets returns a Releaser that can publish a release complete.
func (*Releaser) WithDrafts ¶ added in v0.9.0
func (r *Releaser) WithDrafts(d DraftPublisher) *Releaser
WithDrafts returns a Releaser that finishes a draft an interrupted run left behind, before it creates anything. Spec 0014 D1.
func (*Releaser) WithReader ¶ added in v0.4.0
WithReader returns a Releaser that can finish a release which already exists, by reading it and attaching what it lacks.
type Request ¶
type Request struct {
Owner string
Repo string
// Remote is the clone location and Target the branch that must contain
// the tagged commit.
Remote string
Target string
// Tag is the existing tag to release, e.g. "v1.2.3", or a declared
// component's, e.g. "lint/v0.7.0" (spec 0011 D4).
Tag string
// Assets are already uploaded, each named by where its bytes live. With
// any present the release is created carrying them.
Assets []forge.ReleaseAssetSource
}
Request is one release.
type Source ¶
type Source struct {
Remote string
Target string
Tag string
Commit string
// Dir is the component the tag belongs to, empty for the root: a
// component's notes come from the commits that touch its directory
// (spec 0011 D4).
Dir string
// Scheme reads the repository's tags. Nil means semver, which is what a
// caller that has never heard of schemes means (spec 0016).
Scheme policy.Scheme
}
Source names the release whose notes are to be rendered from history.
type Tree ¶
type Tree interface {
ResolveTag(ctx context.Context, req tree.TagLookup) (string, error)
Contains(ctx context.Context, req tree.ContainsRequest) (bool, error)
FileAt(ctx context.Context, req tree.FileRequest) ([]byte, error)
}
Tree reads the remote: where a tag points, whether a branch carries a commit, and a file at a commit. Satisfied by tree.Recutter.