Document the semantic, maintainer-controlled versioning policy - #131
Merged
Conversation
Make explicit how version.json is managed: the major.minor floor is bumped deliberately by the maintainer for real releases (features / significant changes), while routine maintenance (dependency bumps, CI/doc fixes, template re-syncs) lands on main as a patch and never bumps the minor. develop and main normally share the same version (develop is the prerelease channel); develop is not required to lead main and should not be preemptively bumped. Document the one-off 'hold version.json' step for promoting maintenance when develop's version was already bumped ahead - framed as the exception, not the routine.
Contributor
There was a problem hiding this comment.
Pull request overview
Documents the repository's semantic, maintainer-controlled versioning policy for version.json/NBGV, aiming to prevent accidental minor bumps during routine maintenance.
Changes:
- Add guidance that
version.json(major.minor) is a deliberate floor and should only be bumped for intentional feature releases. - Clarify that routine maintenance should not change
version.jsonand should ship as patches of the current major.minor. - Document the expected relationship between
developandmainversioning and how to handle the exceptional case wheredevelopis bumped ahead.
Describe the build version conceptually (major.minor.height with a prerelease suffix off main, NBGV-computed) instead of asserting an exact prerelease string format that doesn't match what NBGV actually produces.
Drop the change-from-prior framing (no 'not required to lead', 'don't preemptively bump', 'exception not the routine') so the doc states only what is, consistent with the Documentation Style Conventions.
main builds stable, develop builds prereleases. develop leads main by a minor: after each develop -> main release, bump develop's minor in an isolated PR so develop prereleases sort above main's last stable (a shared version sinks develop's prerelease below main's stable in --version/HISTORY/update prompts). Maintenance promotions hold main's version (git checkout main -- version.json) so catch-up work lands as a patch without releasing develop's leading minor.
State the develop-leads rule in all three cross-cutting docs: a develop -> main release is followed by a develop minor bump (isolated bump-version PR) so develop prereleases sort above main's stable, and maintenance promotions hold main's version.
Use <...> placeholders (X.Y.<height>-g<sha>) consistent with the rest of the doc, and state that a held-version maintenance promotion advances main only by its NBGV git height (the SemVer patch position), not a manual patch bump.
ptr727
added a commit
that referenced
this pull request
Jun 8, 2026
Promotes the versioning-policy documentation to `main` (#131): the develop-leads + maintenance-hold model stated in AGENTS.md, README.md, and .github/copilot-instructions.md. Documentation only; version unchanged (maintenance).
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
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.
Documents how
version.jsonis managed, so the versioning model is explicit and propagates to derived repos.developleadsmainby a minor.mainbuilds the stable release (X.Y.height);developbuilds prereleases (X.Y.height-g{sha}). After eachdevelop -> mainrelease, bump develop's minor in an isolatedbump-version-X.YPR so develop's prereleases always sort numerically above main's last stable (at a shared version, develop's prerelease sorts below main's stable - confusing in--version, HISTORY.md, update prompts).mainwithout releasing develop's leading minor viagit checkout main -- version.jsonon the promotion branch (the pattern used for PlexCleaner Promote the Fleet Resync Reports, the copilot-instructions Fixes, and the Upstream Repo-Layout Segment #734). A release promotion carries develop's version, after which develop bumps again.Written in current-state declarative voice. No CI enforcement (documentation only).