A lightweight tag is simply a named pointer to a commit (like a branch that doesn't move). An annotated tag is a full git object containing the tagger name, email, date, and message. Annotated tags can be GPG-signed and are recommended for releases because they provide audit trail and metadata.

Increment the MAJOR version and communicate the change through release notes, migration guides, and deprecation warnings in previous versions. Consider maintaining the previous major version with security patches for a transition period. Use pre-release tags (v2.0.0-beta.1) for testing before the major release.

Deleting a published tag breaks reproducibility. Anyone who has cloned the repo with that tag will have a different commit than new clones. It breaks CI/CD pipelines, package managers, and deployment systems that reference the tag. If a release is bad, yank it from the package registry and release a patch instead.

Pre-release versions use a hyphen suffix: 1.0.0-alpha, 1.0.0-beta.1, 1.0.0-rc.1. They have lower precedence than the associated normal version (1.0.0-alpha < 1.0.0). Pre-release identifiers are compared dot-by-dot: numeric identifiers have lower precedence than alphanumeric ones.

Build metadata (the +build.123 suffix) provides additional information about the build without affecting version precedence. It's ignored when comparing versions, so 1.0.0+build.1 and 1.0.0+build.2 are considered the same version. Use it for CI build numbers, commit SHAs, or compilation timestamps.

Key components: (1) Configure CI to fetch all tags before analyzing commits. (2) Use conventional commits or commit message analysis to determine bump type. (3) Calculate next version based on SemVer rules. (4) Create an annotated tag with metadata (changelog, author, timestamp). (5) Push the tag before publishing the package. (6) Set up branch protection so only specific branches trigger version bumps. Consider using tools like standard-version, release-please, or changesets.

Monorepo challenges: (1) Independent vs unified versioning — each package may need its own version, or all packages share one version. (2) Cross-package dependencies — updating one package's major version may require updates to dependent packages. (3) Tag naming conventions — use prefixes like pkg-a-v1.0.0 or scope tags to subdirectories. (4) Version propagation — decide whether a major bump in one package bumps all packages or just the affected one. Tools like changesets help manage multi-package versioning workflows.

Enforcement strategies: (1) Automated linting — use commit message linting (conventional commits) to catch non-compliant changes. (2) CI validation — reject PRs that claim MAJOR bump without breaking change indicators. (3) Codeowners — require approval from release managers for major bumps. (4) Tooling — use release-please or changesets which auto-generate correct version bumps. (5) Culture — document your versioning policy and include it in onboarding. (6) Registry hooks — some registries enforce version format validation on publish.

npm version automatically creates a commit and annotated tag in one step, then pushes both. It provides consistency between the package.json version and the git tag. Manual tag creation gives you more control over the tag message, allows pre-release versioning with custom preids, and doesn't modify package.json. npm version is simpler for standard releases; manual tagging is better when you need custom workflows or want to decouple versioning from package.json changes.

Use pre-release tags in these scenarios: (1) Feature freeze — near a major release but not yet stable. (2) Beta programs — getting early feedback from users. (3) RC (Release Candidate) — blocking on final testing or sign-offs. (4) Dependency updates — testing major dependency upgrades. (5) Experimental features — shipping new features behind flags. Pre-release tags let consumers opt-in via @next or @beta npm dist-tags, protecting mainstream users from instability.

git describe --tags finds the most recent tag reachable from the current commit. By default it outputs <tag>-<commits>-g<hash> (e.g., v1.2.0-5-gabc1234). Use cases: (1) Generating version strings in build scripts. (2) Debugging production issues — identifying which release a deployed artifact came from. (3) Automation — determining version bump direction by comparing current commit to last tag. --exact-match returns error if the commit itself isn't tagged; --abbrev=0 shows only the tag name.

GPG-signed tags provide cryptographic proof that the tag was created by the key holder, not an attacker who compromised a CI system or developer account. This matters for: (1) Supply chain security — verifying the release came from a trusted source. (2) Regulatory compliance — audit trails with non-repudiation. (3) Package registry verification — some registries verify tag signatures on publish. Signed tags use the git tag -s command and the signature appears in git show --signature. However, consumers must verify the signature and trust the signer's key.

Hotfix workflow: (1) Create a branch from the current release tag (not main/develop). (2) Apply the critical fix. (3) Bump only PATCH version — never mix hotfixes with feature work. (4) Create an annotated tag on the hotfix branch. (5) Merge to main AND the release branch. (6) Publish the patch immediately. This keeps the release branch stable while main continues with next iteration's work. The key discipline: hotfixes are PATCH-only to maintain SemVer guarantees.

CalVer (e.g., 2024.05.15) works for products with predictable release cycles where compatibility matters less than freshness. Trade-offs: CalVer says nothing about breaking changes — you must track breaking changes separately. SemVer excels for libraries and APIs where consumers need version-compatibility guarantees. CalVer is better for consumer products with UI/UX updates where users want to know "how recent is this?" Some projects hybridize: 3.2.0-beta.20240515 combines SemVer with CalVer timestamps.

Debugging steps: (1) Run git log --oneline <tag>^..<tag> to see what commits are included. (2) Compare with expected release commit. (3) If the wrong tag exists, do not delete it if it's been pushed — create a corrected tag with a different name (e.g., v1.2.0-hotfix). (4) Investigate CI logs for why the wrong commit was tagged — common causes: shallow clones (missing tags), race conditions in parallel jobs, or incorrect ref specification. (5) Fix by ensuring CI does git fetch --tags --unshallow before analysis. (6) If the bad release was published, yank it from the registry.

git tag -f <tagname> moves an existing tag to the current commit. It's acceptable only for local, unpublished tags — never force-push published tags. Legitimate use cases: (1) Local development iterations where you're experimenting with versioning. (2) Cleanup before initial push when no one else has the repo. (3) Automated pipelines that recalculate tags in testing environments. If the tag was pushed to a shared remote, the correct response is to create a new tag (e.g., v1.2.0-hotfix2) rather than move the existing one.

npm and Maven treat pre-release as having lower precedence than the stable version: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-rc.1 < 1.0.0. npm's dist-tags separate pre-release versions — installing @beta gets the highest beta. Maven's version comparison follows SemVer strictly. When publishing pre-release packages to npm, use npm publish --tag beta to avoid installing pre-release as @latest. Both tools respect that ^1.0.0 does NOT include 1.0.0-alpha.

Major version lifecycle strategies: (1) Time-boxed support — commit to N months of security patches for the old major version. (2) LTS labels — mark stable major versions as LTS with extended support. (3) Deprecation warnings — use the deprecation field in package.json and runtime warnings. (4) codemods — provide automated migration scripts for breaking changes. (5) Feature flags — keep old behavior accessible via flags while new behavior is default. (6) Communication — announce deprecation in release notes, documentation, and direct outreach to major consumers.

Lock files (package-lock.json, yarn.lock) record exact versions at install time. SemVer ranges (^1.0.0, ~1.2.0) allow updates within constraints. The interaction: (1) Lock files freeze versions — a range like ^1.2.0 may resolve to 1.2.5 today and 1.3.0 tomorrow. (2) SemVer guarantees apply to package authors, not lock file resolvers. (3) For reproducible builds, commit the lock file alongside code changes. (4) CI should use npm ci instead of npm install to enforce lock file compliance. (5) Tags provide commit-level reproducibility complementing lock file version pinning.

Edge cases: (1) Numeric vs alphanumeric — 1.0.0-1 < 1.0.0-alpha because numeric identifiers have lower precedence. (2) Leading zeros — 1.02.0 is NOT semantically 1.2.0; the "02" is a string, not a number. (3) Build metadata comparison — should be ignored entirely when comparing precedence, only preserved for informational purposes. (4) Empty identifiers — 1.0.0-a.b vs 1.0.0-a.b.c; fewer pre-release fields has lower precedence. (5) Boundary cases — 1.0.0-0 < 1.0.0-0.a. Always use a SemVer parsing library for production code rather than string manipulation.