Versioning · XB Field Notes

Git tags pin a release to a commit

Fri, 11 Jun 2027 00:00:00 +0000

A release tag gives people a readable name for a particular source revision. Unlike a branch, it does not advance when another commit is created. However, Git does not make a tag reference physically impossible to change: a user with sufficient access can replace or delete it. The dependable release contract is therefore a combination of a recorded object ID, an immutable-name policy, and controls over who may update release references.

Two kinds of tags

A lightweight tag is a reference directly naming an object, usually a commit. An annotated tag names a separate tag object containing a target, tagger identity, timestamp, message, and optionally a signature. The identity is the person making the tag, which need not be the commit’s author. An annotated tag is not automatically signed just because it contains this metadata.

For an annotated release, git rev-parse refs/tags/v2.4.1 identifies the tag object, while git rev-parse 'refs/tags/v2.4.1^{commit}' resolves its target commit. Record both when annotation or signature identity matters. Checking only the commit misses changes to the tag message or signer; checking only the readable name does not establish either identity.

Why sign a release

git tag -v verifies a signed tag using the configured signing backend and locally available trust information. A successful cryptographic check is useful only if the key is also one your release policy authorizes. A mathematically valid signature from an unknown person does not establish that the project’s maintainer approved the release.

A signed source tag also does not prove that a downloaded binary was built from that source. Artifact checksums, provenance, and the build process establish that separate relationship. Do not pipe verification through head and then trust the pipeline’s last exit status: truncating the display can conceal the verifier’s failure. Capture and enforce the verification command’s own result.

Move with care

Correcting an unpublished local tag is different from replacing one that consumers already fetched. Once distributed, prefer a new version name and document the withdrawn release. A security fix does not require rewriting the old tag; preserving the original reference makes affected deployments easier to identify. Server-side protection should reject unauthorized release-tag updates and deletions.

If an exceptional replacement is approved, publish the exact old and new object IDs and coordinate that single reference with consumers. A blanket forced fetch of every tag can overwrite unrelated local references and should not be routine repair advice. Consumers should never discover silently that two different commits were both presented as the same release.

When it breaks

A floating name such as latest can resolve differently between builds. Record the resolved commit with every artifact and deployment, even if a convenience name is displayed to humans. Reusing a name does not make two builds identical, and pinning a commit does not by itself freeze external dependencies or compiler versions.

Another failure is a release tag available only in one local clone. Ordinary branch pushes do not necessarily transfer it. --follow-tags concerns qualifying annotated tags reachable from the pushed commits, not every local tag. Verify the exact remote reference and its object ID with git ls-remote --tags; a substring match on the version name can accidentally accept another release. Remote visibility proves distribution, not build correctness or signature trust.

Check it quickly

Run this with Python 3 and Git. It creates an isolated temporary repository, supplies an example identity, disables signing for the demonstration, and creates no remote. It never tags the surrounding project. Python removes the disposable repository afterward.

import os
import subprocess
import tempfile

env = {key: value for key, value in os.environ.items() if not key.startswith("GIT_")}
env.update(GIT_CONFIG_NOSYSTEM="1", GIT_CONFIG_GLOBAL=os.devnull)
with tempfile.TemporaryDirectory(prefix="git-tag-demo-") as directory:
 def git(*args, check=True):
 return subprocess.run(
 ["git", "-c", "user.name=Tag Example",
 "-c", "user.email=tags@example.invalid",
 "-c", "commit.gpgsign=false", "-c", "tag.gpgsign=false",
 "-c", "core.hooksPath=/dev/null", *args],
 cwd=directory, env=env, text=True, capture_output=True, check=check,
 )

 git("init", "-q")
 git("commit", "--allow-empty", "-qm", "first")
 first = git("rev-parse", "HEAD").stdout.strip()
 git("tag", "-a", "demo-v1", "-m", "example release")
 git("tag", "demo-bookmark")
 print("annotated:", git("cat-file", "-t", "demo-v1").stdout.strip())
 print("lightweight:", git("cat-file", "-t", "demo-bookmark").stdout.strip())
 git("commit", "--allow-empty", "-qm", "second")
 target = git("rev-parse", "demo-v1^{commit}").stdout.strip()
 print("tag-still-first:", target == first)
 print("head-moved:", git("rev-parse", "HEAD").stdout.strip() != first)
 verification = git("tag", "-v", "demo-v1", check=False)
 print("unsigned-rejected:", verification.returncode != 0)

Expect object types tag and commit, followed by three True results. A new commit advances the branch without moving the tag, and an unsigned annotation fails signature verification. The exercise intentionally does not demonstrate a trusted signature or remote publication; those need the project’s authorized key policy and actual remote-reference checks.

Sources

git-tag reference, tag objects and the consequences of replacing a distributed tag, checked 2026-09-07.
Git tagging basics, lightweight and annotated tags plus sharing behavior, checked 2026-09-07.

Semantic versioning makes compatibility explicit

Sat, 13 Feb 2027 00:00:00 +0000

A dependency version is useful when its publisher and consumers agree on the public contract. Semantic Versioning gives changes a vocabulary: from version 1.0.0 onward, incompatible public API changes require a major increment, compatible additions require a minor increment, and compatible fixes require a patch increment. The number summarizes a claim about a release. It does not inspect its implementation or guarantee that an upgrade will work in your application.

Declare what compatibility covers

A public API can include exported functions, documented command options, configuration formats, response fields, and specified error behavior. Write that boundary clearly enough to decide whether a change violates it. An internal refactor that preserves the contract differs from removing a documented option. A correction to behavior that contradicted the contract can be a compatible bug fix even though somebody observed the old behavior. Explain that change in release notes and test affected consumers.

SemVer requires a minor increment when public functionality is marked deprecated. Removal later requires the appropriate incompatible release. Once a version has been released, its contents must not change; publish another version for a correction. Replacing the bytes behind the same version defeats traceability and can produce different installations from identical dependency declarations.

Major version zero signals initial development, with an API that should not be considered stable. A publisher may describe additional conventions for that phase, but do not assume every zero-major update is compatible. Prereleases have lower precedence than the corresponding normal release. Build metadata after + is ignored when determining precedence, so equal precedence does not imply identical packages or hashes.

When it breaks

A dishonest minor release can break a documented contract despite satisfying a consumer’s version range. A correctly labeled release can also expose an application that relied on undocumented internals. Read the changelog, run meaningful integration checks, and retain a lockfile when the build needs repeatable dependency selection. A lockfile records selected versions; it does not certify their behavior or authenticity.

Package manager ranges are another boundary. SemVer defines versions and precedence, while tools define how constraints select candidates. In node-semver, a caret generally permits changes to the right of the leftmost nonzero component. Consequently, ^0.2.3 excludes 0.3.0, and ^0.0.3 excludes 0.0.4. A tilde with all three components permits patch changes within that minor line.

Prerelease selection has additional rules. A broad stable range does not automatically accept a newer beta. Explicitly allowing a prerelease tuple can admit subsequent prereleases for that tuple. Verify the resolver’s actual behavior instead of applying ordinary string sorting or treating every numerically larger version as an eligible update.

Check it quickly

Save this as semver.py and run python3 semver.py with Node and npm available. Internet access to the public npm registry is required. The script installs semver@7.7.2 into a temporary directory with isolated configuration and cache, disables package scripts, and runs the library’s actual comparison functions. It does not edit the current project’s dependencies.

from pathlib import Path
from tempfile import TemporaryDirectory
import json
import os
import subprocess

with TemporaryDirectory() as directory:
 root = Path(directory)
 user_config = root / 'user.npmrc'
 global_config = root / 'global.npmrc'
 user_config.write_text('')
 global_config.write_text('')
 env = {'PATH': os.environ['PATH'], 'LC_ALL': 'C',
 'NPM_CONFIG_USERCONFIG': str(user_config),
 'NPM_CONFIG_GLOBALCONFIG': str(global_config),
 'NPM_CONFIG_CACHE': str(root / 'cache')}
 subprocess.run(['npm', 'install', '--ignore-scripts', '--no-audit', '--no-fund',
 '--package-lock=false', '--registry=https://registry.npmjs.org',
 'semver@7.7.2'], cwd=root, env=env, check=True, capture_output=True)
 script = r'''
const s = require('semver');
const assert = require('node:assert/strict');
const cases = [
 ['1.9.0', '^1.2.3', true], ['2.0.0', '^1.2.3', false],
 ['1.2.9', '~1.2.3', true], ['1.3.0', '~1.2.3', false],
 ['0.2.9', '^0.2.3', true], ['0.3.0', '^0.2.3', false],
 ['0.0.4', '^0.0.3', false], ['1.3.0-beta.1', '^1.2.3', false],
 ['1.3.0-beta.2', '^1.3.0-beta.1', true]
].map(([version, range, expected]) => {
 const accepted = s.satisfies(version, range);
 assert.equal(accepted, expected);
 return {version, range, accepted};
});
assert.equal(s.compare('1.2.3+build.1', '1.2.3+build.2'), 0);
assert.equal(s.lt('1.3.0-beta.2', '1.3.0'), true);
assert.equal(s.valid('1.02.3'), null);
console.log(JSON.stringify({library: require('semver/package.json').version, cases,
 metadata_precedence_equal: true, prerelease_before_release: true, leading_zero_rejected: true}));
'''
 result = subprocess.run(['node', '-e', script], cwd=root, env=env,
 capture_output=True, text=True, check=True)
 print(json.dumps(json.loads(result.stdout)))

The nine range cases must match their recorded expectations: caret accepts 1.9.0 under ^1.2.3 but rejects 2.0.0; tilde rejects the next minor; the zero-major cases remain narrower. The stable range rejects 1.3.0-beta.1, while the explicitly prerelease range accepts 1.3.0-beta.2.

The remaining assertions establish that two build metadata variants compare equally, a beta precedes its normal release, and a leading zero in 1.02.3 is invalid. These results verify parsing and selection, not the compatibility of any real library update. Pair a proposed version bump with evidence about the changed API and the consumers affected. The version communicates that judgment; release notes and tests make the judgment assessable.

Sources

Semantic Versioning 2.0.0, public API promises, precedence, and initial development, checked 2026-09-13.
npm: node-semver, caret, tilde, and prerelease range behavior, checked 2026-09-13.

Versioning · XB Field Notes

Git tags pin a release to a commit

Two kinds of tags

Why sign a release

Move with care

When it breaks

Check it quickly

Further reading

Sources

Semantic versioning makes compatibility explicit

Declare what compatibility covers

When it breaks

Check it quickly

Further reading

Sources