avizmarlon/version-bump-rules

Version Control — Mandatory Practice

Every software project must maintain a version number. Every change that reaches production or main branch must bump the version in the same commit — no exceptions, no deferral.

Where version lives (by project type)

| Project Type | Version File Location | |---|---| | Node.js / npm package | package.json → "version" field | | WXT (browser extension) | wxt.config.ts → manifest: { version: "x.y.z" } — NOT package.json | | Monorepo (multiple packages) | each affected package.json + manifest.json if extension | | Python | pyproject.toml → [project] version OR __version__ in __init__.py | | Rust / Cargo | Cargo.toml → version field | | Mobile (Expo) | app.json / app.config.ts → version + buildNumber / versionCode | | Bash / Python script (standalone) | comment at top: # v1.2.3 | | Custom setup (no standard file) | VERSION file in root, one line |

Critical: WXT extension gotcha

Browser extensions built with WXT read the version from wxt.config.ts in the manifest block, not from package.json. Bumping only package.json leaves the manifest at the old version, so users see stale version info in the browser extension UI.

Always verify wxt.config.ts when working with WXT projects.

Semantic versioning rules

MAJOR.MINOR.PATCH
  │      │     └── bug fix, cosmetic adjustment, refactor with no external impact
  │      └──────── new feature, backwards-compatible (new behavior, new UI, new integration)
  └─────────────── breaking change (removed behavior, changed public interface, mandatory migration)

When in doubt between MINOR and PATCH? If the end user will notice → MINOR. If only internal code changed → PATCH.

Anti-patterns (mandatory to avoid)

• Committing a new feature without bumping the version → forbidden
• "I'll bump it later" → deferral is not allowed. Bump in the same commit or merge commit
• Version frozen at 0.0.1 while product evolves → traceability failure
• Multiple packages in a monorepo with different versions without justification → align them if they release together

Required workflow

1. Session delivers production-bound change (feature, bugfix, release)
2. Identify the project's version file(s) from the table above
3. Decide the bump level (MAJOR / MINOR / PATCH) using the semver rule
4. Bump the version before committing the code (or include in the commit)
5. Add entry to CHANGELOG.md with the new version at the top

Implementation notes for AI agents

• Gate before commit: if code is shipping, version must bump. If version hasn't bumped, the commit is incomplete.
• Monorepo edge case: if multiple packages are affected but release independently, bump each. If they always release together, keep versions in sync.
• Validation: after bumping, run a quick check (grep, parse JSON/TOML, read source) to confirm the new version is in place and matches the old version + bump you applied.
• CHANGELOG discipline: version number in CHANGELOG must match the version file after the bump. If they diverge, the next AI session or developer has incomplete information about what version contains which features.

Applies to

All software projects, all AI agents (Claude, Codex, Cursor, Gemini), all sessions.