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 ¶
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 shared
// component's or a tag_also directory's, whose release is the root's.
// RootTag names it. Nothing was created, and nothing was wrong (spec
// 0011 D6).
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
}
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 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.