announce

package
v0.21.4 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package announce tells people a release happened.

Whether it is idempotent is the ADAPTER's answer, not this package's, and the two kinds differ in what the medium can be asked.

An adapter whose medium can be READ can tell: the file adapter appends an entry carrying a key and the file it appends to is the record, so a retried pipeline re-reads it and reports Unchanged rather than writing twice (spec 0023 D2). No marker, no database, no lock.

An adapter whose medium cannot be read has no such answer. A webhook execution has no idempotency key and nothing to look up, so Discord delivery is at-least-once and says so rather than implying otherwise (spec 0019 D6).

Everything else colophon does has an answer for being run twice: a release that exists is reported, a tag that exists is left alone, and a comment `apply` posts carries go/forge's idempotency key so the PROVIDER returns the existing one.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Problems

func Problems(results []Result) int

Problems counts the results a person should look at, which is what a report says at the end and what nothing else acts on.

Types

type Announcer

type Announcer interface {
	// Name identifies this adapter in a report and in the manifest.
	Name() string

	// Announce delivers, and says what it did.
	Announce(ctx context.Context, r Release) (Status, error)
}

Announcer delivers one release announcement.

The seam is about the MESSAGE, not the transport. A webhook, a commit to a static site and a call to a mail service have almost nothing in common at the transport level and almost everything in common here: they are all handed a release and asked to say something about it.

type Configured

type Configured struct {
	Announcer Announcer

	// When is the smallest bump this adapter announces. BumpNone announces
	// every release, which is what `when: any` means.
	When policy.Bump
}

Configured is one adapter and the size of release it was asked to announce.

type Noted added in v0.19.1

type Noted interface {
	AnnounceNoted(ctx context.Context, r Release) (Status, string, error)
}

Noted is an Announcer that can say something about a delivery that worked, such as a feed proposed for merging that the forge would not merge. The runner prefers it, because the report is the only place a person reads it.

type Release

type Release struct {
	// Project is the human name — "ffmpeg-wasi" — and Path its full location
	// on the forge.
	Project string
	Path    string

	// Tag is what was cut. Version is what it carries, which is the same
	// string under a scheme whose versions are their own tags.
	Tag     string
	Version string

	// Bump is how far this release moved, under whatever scheme the project
	// uses. It is what a filter is written against, because every scheme
	// answers it and only semver has a patch field (spec 0019 D4).
	Bump policy.Bump

	// Notes are the release's, as the release object carries them.
	Notes string

	// URL is the release page, which is where an announcement points.
	URL string

	// ProjectURL is the repository's page on the forge.
	ProjectURL string

	// Name is the release's own header as the forge shows it. Usually the tag,
	// and allowed not to be: a project whose releases carry a headline.
	Name string

	// ReleasedAt is when the FORGE considers the release published, which is
	// what it sorts its own listing by (go/forge spec 0023). Zero when the
	// forge did not say — never the pipeline's clock, so a record built from
	// it still orders correctly when a job runs late or is retried.
	ReleasedAt time.Time
}

Release is what an announcement is made from.

The NOTES are the foundation and not the text: every adapter is built from them and none of them delivers them as they are. A Discord embed wants a title, a colour and twelve hundred characters; a newsletter wants a subject line and probably the whole thing; a blog post wants front matter and a permalink. So this carries the notes AND the facts they were rendered from, and each adapter decides what to make of them (spec 0019 D7).

type Result

type Result struct {
	Adapter string
	Status  Status

	// Detail is the reason for every status but Announced, and anything a
	// person should know about a delivery that worked.
	Detail string
}

Result is one adapter's outcome.

type Runner

type Runner struct {
	// contains filtered or unexported fields
}

Runner announces a release through every adapter a project configured.

func New

func New(adapters ...Configured) *Runner

New returns a Runner over the adapters, in the order they were configured, which is the order a report lists them.

func (*Runner) Do

func (a *Runner) Do(ctx context.Context, r Release) []Result

Do announces r through each adapter and returns one result each.

It returns no error. A failure against one adapter is a Result, and the others still run: an announcement that did not reach Discord is no reason to withhold one from a mailing list, and neither is a reason to fail a pipeline whose release already succeeded (spec 0019 D2).

type Status

type Status string

Status is what one adapter did.

const (
	// Announced: it was delivered. Under D6 this does not promise it was
	// delivered once.
	Announced Status = "announced"

	// Unchanged: the adapter could tell this release had already been
	// announced, and did not repeat it. Only a medium that can be READ
	// answers this — a blog post that exists, a message with a key the
	// service honours. A webhook cannot, and never reports it.
	Unchanged Status = "unchanged"

	// Skipped: this release is smaller than the adapter was configured to
	// announce, or the adapter has nothing to deliver with.
	Skipped Status = "skipped"

	// Failed: delivery was attempted and did not work. Never fatal: by the
	// time this runs the release is public, and a red pipeline over a chat
	// message is worse signal than a yellow one (spec 0019 D2).
	Failed Status = "failed"
)

Directories

Path Synopsis
Package discord announces a release to a Discord channel through a webhook.
Package discord announces a release to a Discord channel through a webhook.
Package file announces a release by appending it to a structured file in a repository and committing it.
Package file announces a release by appending it to a structured file in a repository and committing it.

Jump to

Keyboard shortcuts

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