IF Commons GitHub

versions

versions, how works are versioned (commons 0026-works-versioning): check finds a record that is wrong, an identity that changed and a version that went back since the base (a version grows at the release, release.ts, and not at every push), bump writes the next version into a work's record, tag creates the annotated (and, where Git is set to sign, signed) tag <slug>-v<version>, notes prints the release notes from the capabilities closed since the last tag, cite writes CITATION.cff from the record, and ledger derives the ledger of releases from the tags.

bun commons/libraries/src/versions.ts check [--base REV] judge every work against the merge base with REV (origin/main by default) bun commons/libraries/src/versions.ts bump WORK --impact major|minor|patch|auto write the next version into WORK's record (auto: the greatest Impact: of the commits since its last tag) bun commons/libraries/src/versions.ts tag WORK [--tier TIER] [--declaration FILE] create the annotated tag at HEAD, signed where Git signs; a regulated harness releases only on its declared tier bun commons/libraries/src/versions.ts notes WORK [--from TAG] release notes (Markdown) from the Closes #N lines of the commits since the last tag bun commons/libraries/src/versions.ts cite WORK [--check] write CITATION.cff (--check: exit 1 where the file is not what the record makes) bun commons/libraries/src/versions.ts ledger [WORK] [--json] [--against FILE] the releases, from the tags; --against finds a tag that moved or is gone since an earlier --json other flags: --repo DIR (the repository, the working folder by default)

A work is named by its slug or by its folder. Exit status: 0 where it did what was asked and found nothing, 1 where it found something (or cite --check finds the file different, or a release is refused), 2 for a usage error (an unknown command, option or work, a work of no version, no commit that states an impact), 3 where the environment cannot do it. A run that could not run says not_run with its reason (Git absent, no repository, a base that cannot be found) and writes no record (FR-031). It reads only Git: a repository on plain Git, with no host, is enough.

Spec: 0001-libraries FR-008

Source: commons/libraries/src/versions.ts

0 of 4 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

checkVersionsfunctionno test imports it
function checkVersions(repo: string, rev?: string): Promise<VersionsCheck>

The version check as data (0026-works-versioning FR-022, FR-040): every work of the repository at repo judged against the merge base with rev (origin/main where not given). It reads only Git, so it runs offline: no host, no network, a base that is any revision the repository holds (a branch, a tag or a commit). A consumer calls this, or run(["check", "--base", rev, "--repo", repo]).

runVersionsfunctionno test imports it
function runVersions(argv: readonly string[], deps?: Deps): Promise<number>

Run the command: the exit status (0, 1 findings, 2 usage, 3 the environment cannot do it).

VersionsChecktypeno test imports it
type VersionsCheck =
  | { readonly kind: "judged"; readonly findings: readonly VersionsFinding[]; readonly works: number; readonly from: string }
  | { readonly kind: "not_run"; readonly reason: string };

What checkVersions found, or why it could not run (not_run, FR-031): the findings, the number of works judged and what they were judged against.

COMMANDSconstno test imports it
const COMMANDS: readonly ["check", "bump", "tag", "notes", "cite", "ledger"]

The commands, in the order the help lists them.

Titles, headings, exports, tables, columns and requirements. Esc closes.