From 842a4f9b0820d1bf9ff3544175b0edd66d51a1af Mon Sep 17 00:00:00 2001 From: Joseph Mearman Date: Tue, 8 Sep 2026 05:14:47 +0100 Subject: [PATCH] docs: rewrite dash-interrupted sentences into plain prose Replace double-hyphen "--" interruptions across README, CONTRIBUTING, config files, and source comments/docstrings with a colon, comma, semicolon, or a sentence split, matching the punctuation each sentence actually calls for. CLI flags such as --frozen-lockfile and --points-at are unaffected. --- .github/workflows/ci.yml | 4 ++-- CONTRIBUTING.md | 6 +++--- README.md | 28 +++++++++++++------------- eslint.config.ts | 2 +- pnpm-workspace.yaml | 4 ++-- release.config.ts | 4 ++-- src/git.test.ts | 2 +- src/git.ts | 4 ++-- src/resolve-build-identity.test.ts | 2 +- src/resolve-build-identity.ts | 2 +- src/resolve-predicted-identity.test.ts | 4 ++-- src/resolve-predicted-identity.ts | 2 +- src/test-repo.ts | 2 +- src/types.ts | 6 +++--- 14 files changed, 36 insertions(+), 36 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6f9d381..99350a8 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -78,7 +78,7 @@ jobs: with: node-version: '22' cache: pnpm - # registry-url is deliberately absent -- setup-node would otherwise write an .npmrc _authToken line that wins over the OIDC token exchange, breaking trusted publishing. + # registry-url is deliberately absent: setup-node would otherwise write an .npmrc _authToken line that wins over the OIDC token exchange, breaking trusted publishing. - run: pnpm install --frozen-lockfile - name: Upgrade npm for OIDC trusted publishing (needs npm CLI >=11.5.1) run: npm install -g npm@latest @@ -87,6 +87,6 @@ jobs: run: HUSKY=0 pnpm exec semantic-release env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - # Blanked, not omitted -- an inherited NPM_TOKEN/NODE_AUTH_TOKEN would otherwise be used in preference to the OIDC exchange. + # Blanked, not omitted: an inherited NPM_TOKEN/NODE_AUTH_TOKEN would otherwise be used in preference to the OIDC exchange. NPM_TOKEN: '' NODE_AUTH_TOKEN: '' diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e45b1f..a6f50cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,12 +16,12 @@ Commits are conventional (`feat:`, `fix:`, `chore:`, ...), enforced by commitlin Every push to `main` runs `.github/workflows/ci.yml`'s `release` job: `semantic-release` analyses commits since the last tag, decides the next version, publishes to npmjs.org, and creates the git tag and GitHub Release. Nothing about the release commands themselves is manual. -**npm trusted publishing (OIDC) cannot bootstrap a package that has never been published before.** npm's own CLI (`npm trust --help`) states this as a hard prerequisite: "Package must exist: The package you're configuring must already exist on the npm registry." There is no way -- via the npmjs.com UI or the `npm trust` CLI -- to configure the trust relationship between this repository's workflow and an npm package name before that name has at least one published version. This is a platform limitation, not something this repository's own CI configuration can work around. +**npm trusted publishing (OIDC) cannot bootstrap a package that has never been published before.** npm's own CLI (`npm trust --help`) states this as a hard prerequisite: "Package must exist: The package you're configuring must already exist on the npm registry." There is no way, via the npmjs.com UI or the `npm trust` CLI, to configure the trust relationship between this repository's workflow and an npm package name before that name has at least one published version. This is a platform limitation, not something this repository's own CI configuration can work around. Concretely, that meant the very first version of this package needed one manual, one-time step before `semantic-release`'s own OIDC-based publish could work unattended for every version after it: 1. A maintainer with npm publish rights ran a single `npm publish` from an authenticated local session (2FA-backed), creating `@exadev/build-identity` on the registry at a low placeholder version. -2. Once the package existed, `npm trust github @exadev/build-identity --repo ExaDev/build-identity --file .github/workflows/ci.yml --allow-publish` registered the trust relationship between this repository's `release` job and the package -- the CLI equivalent of the "Trusted Publisher" section under the package's settings on npmjs.com. +2. Once the package existed, `npm trust github @exadev/build-identity --repo ExaDev/build-identity --file .github/workflows/ci.yml --allow-publish` registered the trust relationship between this repository's `release` job and the package: the CLI equivalent of the "Trusted Publisher" section under the package's settings on npmjs.com. 3. From that point on, `.github/workflows/ci.yml`'s `release` job publishes every subsequent version over OIDC with no stored token at all (see the workflow's own comments on why `registry-url` is omitted from `setup-node` and why `NPM_TOKEN`/`NODE_AUTH_TOKEN` are explicitly blanked in the release step's environment). -If this package's npm name is ever unpublished, transferred, or otherwise needs its trusted-publisher configuration recreated from scratch, repeat steps 1-2 above -- there is no fully-automated path around npm's own package-must-exist requirement. +If this package's npm name is ever unpublished, transferred, or otherwise needs its trusted-publisher configuration recreated from scratch, repeat steps 1-2 above. There is no fully-automated path around npm's own package-must-exist requirement. diff --git a/README.md b/README.md index f414926..f11faa7 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,11 @@ [![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/build-identity) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/@exadev/build-identity) [![Release](https://img.shields.io/github/v/release/ExaDev/build-identity)](https://github.com/ExaDev/build-identity/releases/latest) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/build-identity/ci.yml?branch=main)](https://github.com/ExaDev/build-identity/actions) -> Resolve a build's true identity -- a real, already-tagged release, or the commit it was built from -- from live git state, with an optional predicted-version display layer. +> Resolve a build's true identity from live git state: a real, already-tagged release, or the commit it was built from. Includes an optional predicted-version display layer. ## Why -A build banner or footer link (`v1.4.0`, linking to a release page) is only honest the moment a real release actually exists at that commit. Deriving that label from `package.json` alone, or from a CI environment variable, or from "this is the main branch so it must be the latest release" is exactly how a link to a release page that doesn't exist yet gets shipped -- typically the commit that triggers the release pipeline itself, before the tag and GitHub Release the link points at have actually been created. This package makes that check live and unavoidable: it shells out to git, checks whether the release tag genuinely points at `HEAD` right now, and only then returns a `'release'` identity. +A build banner or footer link (`v1.4.0`, linking to a release page) is only honest the moment a real release actually exists at that commit. Deriving that label from `package.json` alone, or from a CI environment variable, or from "this is the main branch so it must be the latest release" is exactly how a link to a release page that doesn't exist yet gets shipped, typically on the commit that triggers the release pipeline itself, before the tag and GitHub Release the link points at have actually been created. This package makes that check live and unavoidable: it shells out to git, checks whether the release tag genuinely points at `HEAD` right now, and only then returns a `'release'` identity. ## Getting started @@ -37,13 +37,13 @@ interface ResolveBuildIdentityOptions { } ``` -- **`repoRoot`** -- path to the git working tree to inspect. Must contain `package.json` at its root; that file's `"version"` field is the released version this function checks for. -- **`repoSlug`** -- the GitHub `"owner/repo"` slug used to build both the release and commit URLs (e.g. `"exadev/build-identity"`). -- **`options.tagName`** -- turns the version into the tag name expected to mark its release. The default assumes the common `v` convention (`"1.4.0"` -> `"v1.4.0"`); pass your own function for a repo that tags differently (a bare version, a package-scoped prefix in a monorepo, and so on). +- **`repoRoot`**: path to the git working tree to inspect. Must contain `package.json` at its root; that file's `"version"` field is the released version this function checks for. +- **`repoSlug`**: the GitHub `"owner/repo"` slug used to build both the release and commit URLs (e.g. `"exadev/build-identity"`). +- **`options.tagName`**: turns the version into the tag name expected to mark its release. The default assumes the common `v` convention (`"1.4.0"` -> `"v1.4.0"`); pass your own function for a repo that tags differently (a bare version, a package-scoped prefix in a monorepo, and so on). -**The one property this function exists to guarantee:** it returns `kind: 'release'` if, and only if, a tag named `tagName(version)` provably points at the exact commit `HEAD` is on right now -- checked live against git (`git tag --list --points-at HEAD`), never inferred from `package.json`, an environment variable, or any other proxy that could be true before the tag actually exists. Every other case, including a commit sitting directly on top of the commit a release will eventually tag, returns `kind: 'commit'` instead, with `version` set to the short commit hash (there is no released version to show yet) and `url` pointing at that exact commit's permalink (using the full SHA, not the short one, so the link stays a valid, unambiguous permalink). +**The one property this function exists to guarantee:** it returns `kind: 'release'` if, and only if, a tag named `tagName(version)` provably points at the exact commit `HEAD` is on right now: checked live against git (`git tag --list --points-at HEAD`), never inferred from `package.json`, an environment variable, or any other proxy that could be true before the tag actually exists. Every other case, including a commit sitting directly on top of the commit a release will eventually tag, returns `kind: 'commit'` instead, with `version` set to the short commit hash (there is no released version to show yet) and `url` pointing at that exact commit's permalink (using the full SHA, not the short one, so the link stays a valid, unambiguous permalink). -`resolveBuildIdentity` throws rather than defaulting whenever it can't establish a real identity -- `repoRoot` isn't a git repository, `package.json` is missing or has no non-empty string `"version"` field, or `repoSlug` isn't a real `"owner/repo"` slug. There is no sensible placeholder identity for a build that isn't sitting in real, readable git history. +`resolveBuildIdentity` throws rather than defaulting whenever it can't establish a real identity: `repoRoot` isn't a git repository, `package.json` is missing or has no non-empty string `"version"` field, or `repoSlug` isn't a real `"owner/repo"` slug. There is no sensible placeholder identity for a build that isn't sitting in real, readable git history. ## `resolvePredictedIdentity(build, predictedVersion)` @@ -51,13 +51,13 @@ interface ResolveBuildIdentityOptions { function resolvePredictedIdentity(build: BuildIdentity, predictedVersion: string | undefined): BuildIdentity & { predicted?: boolean }; ``` -An unreleased build's `version` is a short commit hash, which isn't always what you want to show a user -- often what's actually useful is *the version this commit will become once it releases*. This function lets a caller upgrade the displayed label to a predicted version (e.g. computed by running a commit-analyzer-style tool such as `semantic-release`'s own dry-run mode) without ever upgrading the URL to a release page that doesn't exist yet: +An unreleased build's `version` is a short commit hash, which isn't always what you want to show a user. Often what's actually useful is *the version this commit will become once it releases*. This function lets a caller upgrade the displayed label to a predicted version (e.g. computed by running a commit-analyzer-style tool such as `semantic-release`'s own dry-run mode) without ever upgrading the URL to a release page that doesn't exist yet: -- If `build.kind === 'release'`, it is returned **completely unchanged** -- a confirmed release always wins outright, prediction or not. -- Otherwise, when `predictedVersion` is a real, non-empty string, the result's `version` becomes that (trimmed) prediction, `predicted` becomes `true`, and `url`/`date` are copied verbatim from `build` -- the link still points at the real commit. +- If `build.kind === 'release'`, it is returned **completely unchanged**: a confirmed release always wins outright, prediction or not. +- Otherwise, when `predictedVersion` is a real, non-empty string, the result's `version` becomes that (trimmed) prediction, `predicted` becomes `true`, and `url`/`date` are copied verbatim from `build`, so the link still points at the real commit. - With no usable prediction (`undefined`, empty, or whitespace-only), `build` is returned unchanged. -This function does no git or filesystem access of its own -- computing the predicted version is entirely the caller's job, kept deliberately out of this package's core so the one property `resolveBuildIdentity` guarantees stays easy to audit on its own. +This function does no git or filesystem access of its own. Computing the predicted version is entirely the caller's job, kept deliberately out of this package's core so the one property `resolveBuildIdentity` guarantees stays easy to audit on its own. ```ts import { resolveBuildIdentity, resolvePredictedIdentity } from '@exadev/build-identity'; @@ -69,7 +69,7 @@ const identity = resolvePredictedIdentity(build, predictedVersion); ## Framework-agnosticism -This package does pure Node.js filesystem and git access only -- no bundler, framework, or UI assumptions. Wiring its result into a running app is a build-time concern for whichever bundler that app already uses, done in that bundler's own config file, not in this package. +This package does pure Node.js filesystem and git access only, with no bundler, framework, or UI assumptions. Wiring its result into a running app is a build-time concern for whichever bundler that app already uses, done in that bundler's own config file, not in this package. ### Next.js @@ -109,11 +109,11 @@ export default defineConfig({ }); ``` -Either way, the values are inlined at build time -- the running app never shells out to git itself, and `resolveBuildIdentity`/`resolvePredictedIdentity` never ship as part of the app's own bundle. +Either way, the values are inlined at build time: the running app never shells out to git itself, and `resolveBuildIdentity`/`resolvePredictedIdentity` never ship as part of the app's own bundle. ## Conventions -British English throughout. Conventional commits, enforced by commitlint (`commitlint.config.ts`) and released automatically by `semantic-release` (`release.config.ts`) on every push to `main`. Strict TypeScript, no `any`, no type assertions -- see `eslint.config.ts`, which lints this package with `@exadev/eslint-config`. +British English throughout. Conventional commits, enforced by commitlint (`commitlint.config.ts`) and released automatically by `semantic-release` (`release.config.ts`) on every push to `main`. Strict TypeScript, no `any`, no type assertions. See `eslint.config.ts`, which lints this package with `@exadev/eslint-config`. ## Publishing diff --git a/eslint.config.ts b/eslint.config.ts index 83c4321..4e8fb9a 100644 --- a/eslint.config.ts +++ b/eslint.config.ts @@ -11,6 +11,6 @@ export default defineConfig( }, }, ...exadev, - // src/index.ts is this package's own entry-point barrel -- keep it, don't ban it. + // src/index.ts is this package's own entry-point barrel. Keep it, don't ban it. { files: ['src/index.ts'], rules: { 'exadev/barrel-policy': ['error', { mode: 'single' }] } }, ); diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 3f43c80..94ed689 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -1,7 +1,7 @@ -# This is a single-package repo, not a real pnpm workspace -- packages is deliberately empty. Its only purpose is to give turbo a workspace root to anchor local task caching against, matching the same pattern used across ExaDev's other single-package tooling repos. +# This is a single-package repo, not a real pnpm workspace: packages is deliberately empty. Its only purpose is to give turbo a workspace root to anchor local task caching against, matching the same pattern used across ExaDev's other single-package tooling repos. packages: [] -# Pins transitive dependency versions that would otherwise resolve to the newest matching release -- kept in step with @exadev/eslint-config's own known-good resolutions so a fresh install doesn't pick up a patch release still inside the org's minimum-release-age window. +# Pins transitive dependency versions that would otherwise resolve to the newest matching release, kept in step with @exadev/eslint-config's own known-good resolutions so a fresh install doesn't pick up a patch release still inside the org's minimum-release-age window. overrides: '@eslint/plugin-kit': 0.7.2 '@typescript-eslint/eslint-plugin': 8.67.0 diff --git a/release.config.ts b/release.config.ts index fd6d536..dd108e6 100644 --- a/release.config.ts +++ b/release.config.ts @@ -25,7 +25,7 @@ export const commitTypes: readonly CommitType[] = [ ]; /** - * Runs on `main`. Analyses commits since the last tag, bumps the version, publishes to npmjs.org (trusted OIDC publishing, no stored token -- see .github/workflows/ci.yml), creates a versioned tag and GitHub Release with generated notes, and commits CHANGELOG.md + package.json back to main. + * Runs on `main`. Analyses commits since the last tag, bumps the version, publishes to npmjs.org (trusted OIDC publishing, no stored token; see .github/workflows/ci.yml), creates a versioned tag and GitHub Release with generated notes, and commits CHANGELOG.md + package.json back to main. */ const config: Options = { branches: ['main'], @@ -40,7 +40,7 @@ const config: Options = { [ '@semantic-release/release-notes-generator', { - // Deliberately angular, not conventionalcommits -- conventional-changelog-writer's bundled commit partial doesn't match the conventionalcommits preset's function-based partial signature, producing a changelog with a version header and nothing under it. + // Deliberately angular, not conventionalcommits: conventional-changelog-writer's bundled commit partial doesn't match the conventionalcommits preset's function-based partial signature, producing a changelog with a version header and nothing under it. preset: 'angular', }, ], diff --git a/src/git.test.ts b/src/git.test.ts index 2aac2f9..2c3fabc 100644 --- a/src/git.test.ts +++ b/src/git.test.ts @@ -54,7 +54,7 @@ describe('tagPointsAtHead', () => { expect(tagPointsAtHead(repo.root, 'v1.0.0')).toBe(true); }); - it('is false when the tag exists but HEAD has since moved past it -- the case that must never be mistaken for a release', () => { + it('is false when the tag exists but HEAD has since moved past it: the case that must never be mistaken for a release', () => { repo = createTestRepo(); repo.tag('v1.0.0'); repo.commit(); diff --git a/src/git.ts b/src/git.ts index 19e101e..e23a373 100644 --- a/src/git.ts +++ b/src/git.ts @@ -12,7 +12,7 @@ function runGit(repoRoot: string, args: readonly string[]): string { } /** - * Reads HEAD's full hash, short hash, and committer date from the given git working tree. Throws whatever `git` itself throws (e.g. `repoRoot` is not a git repository, or has no commits) -- there is no sensible default identity for a build that isn't sitting in real git history. + * Reads HEAD's full hash, short hash, and committer date from the given git working tree. Throws whatever `git` itself throws (e.g. `repoRoot` is not a git repository, or has no commits). There is no sensible default identity for a build that isn't sitting in real git history. */ export function getHeadCommit(repoRoot: string): HeadCommit { const fullSha = runGit(repoRoot, ['rev-parse', 'HEAD']); @@ -22,7 +22,7 @@ export function getHeadCommit(repoRoot: string): HeadCommit { } /** - * True only if `tagName` both exists and points at the exact commit HEAD is on right now. Uses `git tag --list --points-at HEAD`, which returns `tagName` itself when both hold and nothing otherwise -- there is no separate "tag exists but points elsewhere" case to confuse this with. + * True only if `tagName` both exists and points at the exact commit HEAD is on right now. Uses `git tag --list --points-at HEAD`, which returns `tagName` itself when both hold and nothing otherwise. There is no separate "tag exists but points elsewhere" case to confuse this with. */ export function tagPointsAtHead(repoRoot: string, tagName: string): boolean { const output = runGit(repoRoot, ['tag', '--list', tagName, '--points-at', 'HEAD']); diff --git a/src/resolve-build-identity.test.ts b/src/resolve-build-identity.test.ts index ab70a67..b566898 100644 --- a/src/resolve-build-identity.test.ts +++ b/src/resolve-build-identity.test.ts @@ -30,7 +30,7 @@ describe('resolveBuildIdentity', () => { expect(identity.date).toMatch(/^\d{4}-\d{2}-\d{2}T/); }); - it('never claims a release when the matching tag exists but HEAD has since moved past it -- the core correctness property', () => { + it('never claims a release when the matching tag exists but HEAD has since moved past it: the core correctness property', () => { repo = createTestRepo({ name: 'fixture', version: '1.4.0' }); repo.tag('v1.4.0'); repo.commit('feat: something new after the release tag'); diff --git a/src/resolve-build-identity.ts b/src/resolve-build-identity.ts index 4579c47..6d27aec 100644 --- a/src/resolve-build-identity.ts +++ b/src/resolve-build-identity.ts @@ -38,7 +38,7 @@ function assertRepoSlug(repoSlug: string): void { /** * Resolves what the current build actually is: a real, already-tagged release, or a build made from a commit that hasn't been released yet. * - * This is the one property the whole package exists to guarantee: `kind: 'release'` is returned if and only if a tag named `tagName(version)` (default `v${version}`) provably points at the exact commit HEAD is on right now, checked live against git -- never inferred from `package.json` alone, a CI environment variable, or any other proxy that could be true before the tag actually exists. A caller can render `url` as a link the moment it gets a result back, in either case, without first checking whether that link is real. + * This is the one property the whole package exists to guarantee: `kind: 'release'` is returned if and only if a tag named `tagName(version)` (default `v${version}`) provably points at the exact commit HEAD is on right now. This is checked live against git, never inferred from `package.json` alone, a CI environment variable, or any other proxy that could be true before the tag actually exists. A caller can render `url` as a link the moment it gets a result back, in either case, without first checking whether that link is real. * * @param repoRoot Path to the git working tree to inspect (must contain `package.json` at its root). * @param repoSlug The GitHub `owner/repo` slug used to build both release and commit URLs. diff --git a/src/resolve-predicted-identity.test.ts b/src/resolve-predicted-identity.test.ts index 00ab60e..7ac855f 100644 --- a/src/resolve-predicted-identity.test.ts +++ b/src/resolve-predicted-identity.test.ts @@ -41,13 +41,13 @@ describe('resolvePredictedIdentity', () => { expect(resolvePredictedIdentity(commit, predicted)).toBe(commit); }); - it('never lets a predicted version leak into the URL -- a caller can never render a link to a release that does not exist', () => { + it('never lets a predicted version leak into the URL: a caller can never render a link to a release that does not exist', () => { const result = resolvePredictedIdentity(commit, '99.0.0'); expect(result.url).toBe(commit.url); expect(result.url).not.toContain('99.0.0'); }); - it('does no git or filesystem access of its own -- it is a pure transform of its two arguments', () => { + it('does no git or filesystem access of its own: it is a pure transform of its two arguments', () => { const before = { ...commit }; resolvePredictedIdentity(commit, '1.5.0'); expect(commit).toEqual(before); diff --git a/src/resolve-predicted-identity.ts b/src/resolve-predicted-identity.ts index a7144b0..9765bc5 100644 --- a/src/resolve-predicted-identity.ts +++ b/src/resolve-predicted-identity.ts @@ -3,7 +3,7 @@ import type { BuildIdentity } from './types'; /** * Upgrades an unreleased build's displayed version to a predicted one (e.g. the version a commit-analyzer-style tool computes the next release will be), without ever upgrading its URL. * - * A confirmed release always wins outright: if `build.kind === 'release'`, this returns `build` completely unchanged, prediction or not -- a real, already-tagged release can never be second-guessed by a prediction. Otherwise, when `predictedVersion` is a real, non-empty string, the returned `version` becomes that predicted label, `predicted` becomes `true`, and `url` is copied verbatim from `build` -- it still points at the real commit, never at a release page that doesn't exist yet. With no usable prediction, `build` is returned unchanged. + * A confirmed release always wins outright: if `build.kind === 'release'`, this returns `build` completely unchanged, prediction or not. A real, already-tagged release can never be second-guessed by a prediction. Otherwise, when `predictedVersion` is a real, non-empty string, the returned `version` becomes that predicted label, `predicted` becomes `true`, and `url` is copied verbatim from `build`, so it still points at the real commit, never at a release page that doesn't exist yet. With no usable prediction, `build` is returned unchanged. * * This function does no git or filesystem access of its own: predicting the next version (e.g. by running a commit-analyzer) is entirely the caller's job. It exists to keep that prediction, and the guarantee `resolveBuildIdentity` makes about `url`, cleanly separate. */ diff --git a/src/test-repo.ts b/src/test-repo.ts index a23c4f7..9506939 100644 --- a/src/test-repo.ts +++ b/src/test-repo.ts @@ -42,7 +42,7 @@ export function createTestRepo(packageJson: Record = { name: 'f return git(root, ['rev-parse', 'HEAD']); }, tag(name: string) { - // -c tag.gpgSign=false: this machine's global git config signs every tag by default, which needs a GPG agent and turns a plain lightweight tag into an annotated one requiring a message -- neither of which a disposable test fixture should depend on. + // -c tag.gpgSign=false: this machine's global git config signs every tag by default, which needs a GPG agent and turns a plain lightweight tag into an annotated one requiring a message, neither of which a disposable test fixture should depend on. git(root, ['-c', 'tag.gpgSign=false', 'tag', name]); }, cleanup() { diff --git a/src/types.ts b/src/types.ts index 3251af8..b662077 100644 --- a/src/types.ts +++ b/src/types.ts @@ -1,7 +1,7 @@ /** * What a build actually is, as far as git can prove it right now. * - * A build is `'release'` only when a real, existing tag points at the exact commit being built -- never when a release is merely expected, scheduled, or about to happen. Every other build, including one sitting directly on top of the commit a release will eventually tag, is `'commit'`. + * A build is `'release'` only when a real, existing tag points at the exact commit being built, never when a release is merely expected, scheduled, or about to happen. Every other build, including one sitting directly on top of the commit a release will eventually tag, is `'commit'`. */ export type BuildIdentity = | { @@ -15,7 +15,7 @@ export type BuildIdentity = } | { readonly kind: 'commit'; - /** The short commit hash this build was made from -- there is no released version to show yet. */ + /** The short commit hash this build was made from. There is no released version to show yet. */ readonly version: string; /** The permalink to this exact commit. */ readonly url: string; @@ -25,7 +25,7 @@ export type BuildIdentity = export interface ResolveBuildIdentityOptions { /** - * Turns the version read from `package.json` into the git tag name that is expected to mark its release. Defaults to a `v` prefix (`"1.4.0"` -> `"v1.4.0"`), the convention this package's own release tooling and GitHub's own release UI both use -- override it for a repo that tags releases differently (a bare version, a package-scoped prefix in a monorepo, and so on). + * Turns the version read from `package.json` into the git tag name that is expected to mark its release. Defaults to a `v` prefix (`"1.4.0"` -> `"v1.4.0"`), the convention this package's own release tooling and GitHub's own release UI both use. Override it for a repo that tags releases differently (a bare version, a package-scoped prefix in a monorepo, and so on). */ readonly tagName?: (version: string) => string; }