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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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_SHAandCI_DEFAULT_BRANCHand passes them in. A library call takes the module as an argument, and the base and branch asCheckOptions.DefaultBaseandCheckOptions.DefaultBranch.- It does not print
A truncated changelog, a created tag and a passing check are values:
Document.Repo.Truncated, a nil error fromTag, and aCheckReportwhoseErris nil. A truncated changelog looks normal, so a caller that allows a shallow clone should say so itself, as the command line does.Releasewrites the output of mage and sq toReleaseOptions.Logonly, and gives sqReleaseOptions.Stdinonly.- It does not cache attribution
Every call works it out again from the tags, so a
Repoheld across a new tag sees it. The limit on git subprocesses applies to each call.
Errors to branch on¶
Error |
When |
|---|---|
|
the repository is a shallow clone, and it was not opened with |
|
the repository has modules and the call named none; the error lists them |
|
|
|
|
|
|
|
|
|
|
|
in |
|
|
|
|
|
|
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.