docs: document the versioning / release-please convention#96
Merged
Conversation
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) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes the "document the
0.0.0versioning convention" task (v2.0.0 milestone).Problem
package.jsondeclares"version": "0.0.0". The field'sdescriptionexplains it's intentional (source of truth = git tags +.release-please-manifest.json), but that convention wasn't documented anywhere a contributor looks first.Changes
versionfield is pinned to0.0.0on purpose and must not be hand-edited; the real version lives in git tags +.release-please-manifest.json; release-please'ssimplerelease type records the bump in the manifest, notpackage.json(which is why it stays0.0.0). Links onward todocs/RELEASING.mdfor the full flow.0.0.0is sent straight to the section.Acceptance criteria
Note on matching Aurelius / Nerva
I checked both. Aurelius documents a "Release Process" using
commit-and-tag-version(.versionrc.json), wherepackage.json's version is kept in sync — the opposite of Flavian's0.0.0placeholder. Nerva has no versioning section yet. So there's no verbatim wording to match, and matching it literally would be inaccurate (different tool, different package.json behavior). I mirrored Aurelius's structure and "don't hand-edit the version" guidance while accurately describing Flavian's release-please flow. If the three repos later standardize on one tool/wording, this section should be reconciled then.🤖 Generated with Claude Code