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
- Session delivers production-bound change (feature, bugfix, release)
- Identify the project's version file(s) from the table above
- Decide the bump level (MAJOR / MINOR / PATCH) using the semver rule
- Bump the version before committing the code (or include in the commit)
- 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.
1---2name: version-bump-rules3description: Keep versions up-to-date — every production change bumps the version in the same commit. Semantic versioning rules. Special handling for WXT browser extensions (version in wxt.config.ts, not package.json). Use when working with version, release, semver, changelog, MAJOR.MINOR.PATCH, breaking change, or deploying code.4---56## Version Control — Mandatory Practice78Every 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.910### Where version lives (by project type)1112| Project Type | Version File Location |13|---|---|14| Node.js / npm package | `package.json` → `"version"` field |15| **WXT (browser extension)** | **`wxt.config.ts` → `manifest: { version: "x.y.z" }` — NOT `package.json`** |16| Monorepo (multiple packages) | each affected `package.json` + `manifest.json` if extension |17| Python | `pyproject.toml` → `[project] version` OR `__version__` in `__init__.py` |18| Rust / Cargo | `Cargo.toml` → `version` field |19| Mobile (Expo) | `app.json` / `app.config.ts` → `version` + `buildNumber` / `versionCode` |20| Bash / Python script (standalone) | comment at top: `# v1.2.3` |21| Custom setup (no standard file) | `VERSION` file in root, one line |2223#### Critical: WXT extension gotcha2425Browser 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.2627**Always verify `wxt.config.ts` when working with WXT projects.**2829### Semantic versioning rules3031```32MAJOR.MINOR.PATCH33 │ │ └── bug fix, cosmetic adjustment, refactor with no external impact34 │ └──────── new feature, backwards-compatible (new behavior, new UI, new integration)35 └─────────────── breaking change (removed behavior, changed public interface, mandatory migration)36```3738**When in doubt between MINOR and PATCH?** If the end user will notice → MINOR. If only internal code changed → PATCH.3940### Anti-patterns (mandatory to avoid)4142- Committing a new feature without bumping the version → forbidden43- "I'll bump it later" → deferral is not allowed. Bump in the same commit or merge commit44- Version frozen at 0.0.1 while product evolves → traceability failure45- Multiple packages in a monorepo with different versions without justification → align them if they release together4647### Required workflow48491. Session delivers production-bound change (feature, bugfix, release)502. Identify the project's version file(s) from the table above513. Decide the bump level (MAJOR / MINOR / PATCH) using the semver rule524. Bump the version before committing the code (or include in the commit)535. Add entry to `CHANGELOG.md` with the new version at the top5455### Implementation notes for AI agents5657- **Gate before commit:** if code is shipping, version must bump. If version hasn't bumped, the commit is incomplete.58- **Monorepo edge case:** if multiple packages are affected but release independently, bump each. If they always release together, keep versions in sync.59- **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.60- **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.6162### Applies to6364All software projects, all AI agents (Claude, Codex, Cursor, Gemini), all sessions.
avizmarlon