From ec7f912157dd77384b02dfbef95f4e48282b3788 Mon Sep 17 00:00:00 2001 From: PAMulligan Date: Sun, 31 May 2026 04:11:03 -0400 Subject: [PATCH] docs: document the versioning / release-please convention package.json pins `version` to 0.0.0 on purpose, but that convention wasn't explained anywhere a contributor looks first. Add a "Versioning" section to CONTRIBUTING.md (after Commit Message Format) covering: don't hand-edit the package.json version, the source of truth is git tags + the release-please manifest, and why the `simple` release type leaves package.json at 0.0.0. Add a short pointer in README.md next to the docs links. Mirrors the structure and "don't hand-edit the version" guidance of Aurelius's release section; Flavian's mechanism differs (release-please vs commit-and-tag-version), so the wording describes the actual release-please flow. Nerva has no versioning section to match yet. Co-Authored-By: Claude Opus 4.8 (1M context) --- CONTRIBUTING.md | 18 ++++++++++++++++++ README.md | 2 ++ 2 files changed, 20 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 78eb67d..8e93c4f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -91,6 +91,24 @@ PRs with invalid commit messages will fail the `commitlint` check. See [docs/RELEASING.md](docs/RELEASING.md) for how these commits become tagged releases. +## Versioning + +The `version` field in `package.json` is intentionally pinned to `0.0.0` and is +**not** the repository version — **do not edit it by hand**. The source of truth +for the released version is the latest `vX.Y.Z` git tag together with +[`.release-please-manifest.json`](.release-please-manifest.json). + +Versioning is automated by [release-please](https://github.com/googleapis/release-please). +The [Conventional Commit](#commit-message-format) types above drive the semver +bump; release-please opens a **Release PR** that updates the manifest and +`CHANGELOG.md`, and merging that PR creates the `vX.Y.Z` tag and GitHub Release. +Because the project uses release-please's `simple` release type, the bump is +recorded in `.release-please-manifest.json` rather than `package.json` — which +is exactly why `package.json` stays at `0.0.0`. + +See [docs/RELEASING.md](docs/RELEASING.md) for the full flow, the version-bump +rules, and overrides (e.g. the `Release-As:` footer). + ## Coding Standards - Follow [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/) diff --git a/README.md b/README.md index 7c6067d..8f9d38d 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,8 @@ Site at http://localhost:8080 · Admin at /wp-admin · Database UI at :8081. **More docs:** [docs/QUICK-START.md](docs/QUICK-START.md) · [LOCAL-DEVELOPMENT.md](LOCAL-DEVELOPMENT.md) · [docs/docker-troubleshooting.md](docs/docker-troubleshooting.md) +> **Versioning:** `package.json` declares `0.0.0` on purpose — the real version lives in git tags + `.release-please-manifest.json`. See [Versioning](CONTRIBUTING.md#versioning) in CONTRIBUTING.md. +
Alternative: use as a wp-content directory in an existing WordPress install