The Go API

A Go program can drive moneta without running the binary. The root package of the module is the same changelog the command line prints, with types instead of text:

$ go get gitlab.com/terryp/moneta

The command line is a client of this package, so the two cannot disagree. Each command is one method, the flags are its arguments, and everything the command prints comes back as a value. The reference is on pkg.go.dev; this page is the part worth knowing before reading it.

Reading a changelog

repo, err := moneta.Open(ctx, ".")
cl, err := repo.Changelog("")   // or the module's name
doc, err := cl.Document(ctx, moneta.DocumentOptions{Version: moneta.Latest})

Open finds the repository that holds a directory and reads its omniblack.yaml. Changelog picks one changelog out of it, and ChangelogAt(dir) picks the module whose path holds a directory, as the command line does with the working directory.

Command

Method

moneta render --format json

Changelog.Document, a *schema.Document

moneta render

Changelog.Render, to an io.Writer

moneta list

Changelog.Versions

moneta next, --bump-only

Changelog.Next, a Suggestion

moneta next --tag, --push

Changelog.Tag

moneta check

Repo.Check, a *CheckReport

moneta commit-msg

Repo.CheckCommitMessage, Repo.StripCommitMessage

moneta new, --dry-run

Repo.ComposeFragment, then Repo.WriteFragment

The results are the types of the schema package, which is the JSON contract moneta render --format json prints and the Sphinx extension reads. They change only with its schema_version.

create and commit have no method, because they are forms, $EDITOR and git commit. Their non-interactive halves are ComposeFragment, ReviseFragment and ParseCommitMessage.

Releasing

Next works out the version and Tag creates it. They are two calls because they are two acts: a release tool may show the suggestion, ask, or change its mind in between.

next, err := cl.Next(ctx)
err = cl.Tag(ctx, next, moneta.TagOptions{Push: true})

// The notes for the release page: the release on HEAD, without the heading
// the page's title already has.
err = cl.Render(ctx, w, moneta.FormatMarkdown, moneta.RenderOptions{
    DocumentOptions: moneta.DocumentOptions{Version: moneta.Current},
    Body:            true,
})

Tag tags the commit Next worked the version out for, not whatever HEAD is by then. It refuses a commit that already has a release tag, and a suggestion with nothing pending, unless TagOptions.Force is set. TagOptions.Sign signs the tag with git’s own signing configuration, and fails rather than leave an unsigned tag.

Repo.Release is moneta release and moneta snapshot: Next, Tag and Render for each module, with the build, the archives, the signature, the push and the upload in between. ReleaseOptions.Mode says how far it goes.

results, err := repo.Release(ctx, moneta.ReleaseOptions{
    Mode:    moneta.ReleaseSnapshot,
    Modules: []string{"core"},
    Log:     os.Stderr, // mage's and sq's output; discarded when nil
})

A magefile that moneta release runs imports gitlab.com/terryp/moneta/buildenv to read what it is to build. See Cutting a release.

Checking

A finding is not an error. Repo.Check returns a report of what it found (the broken fragments, the commit messages with an unknown scope, and whether the branch owes a fragment) and keeps its error for a check that could not run: no base to compare with, a ref that is not a commit, git failing. CheckReport.Err joins the findings into the text moneta check prints, for a caller that only wants pass or fail.

What the library does not do

It does not read the environment

The command line reads $MONETA_MODULE, CI_MERGE_REQUEST_DIFF_BASE_SHA and CI_DEFAULT_BRANCH and passes them in. A library call takes the module as an argument, and the base and branch as CheckOptions.DefaultBase and CheckOptions.DefaultBranch.

It does not print

A truncated changelog, a created tag and a passing check are values: Document.Repo.Truncated, a nil error from Tag, and a CheckReport whose Err is nil. A truncated changelog looks normal, so a caller that allows a shallow clone should say so itself, as the command line does. Release writes the output of mage and sq to ReleaseOptions.Log only, and gives sq ReleaseOptions.Stdin only.

It does not cache attribution

Every call works it out again from the tags, so a Repo held across a new tag sees it. The limit on git subprocesses applies to each call.

Errors to branch on

Error

When

ErrShallow

the repository is a shallow clone, and it was not opened with AllowShallow

ErrModuleRequired, *ModuleRequiredError

the repository has modules and the call named none; the error lists them

*ConfigError

omniblack.yaml could not be read or is not valid

ErrNoHeadTag

Current was asked for and HEAD has no release tag

*UnknownVersionError

Release(name) names a version the changelog does not have

ErrNothingPending, ErrHeadTagged

Tag without Force

*PushError

Tag created the tag and the push failed; push it, do not tag again

ErrFragmentOwed

in CheckReport.Err: the branch owes a fragment

ErrNoBase

Check had to compare the branch with something, and nothing named a base

*FragmentExistsError

WriteFragment found the file already there; matches fs.ErrExist

ErrNoReleaseConfig

Release in a repository with no moneta.release block

Every message is the one the command line prints.

Stability

The module is at v0, so a minor release may change the API. Only the root package and schema are public: the attribution algorithm is under internal/ because it is still changing, and exporting it would freeze it.