Conversation
Documents how `version.json` is managed, so the versioning model is
explicit and propagates to derived repos.
- **`develop` leads `main` by a minor.** `main` builds the stable
release (`X.Y.height`); `develop` builds prereleases
(`X.Y.height-g{sha}`). After each `develop -> main` release, bump
develop's minor in an isolated `bump-version-X.Y` PR 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).
- **Maintenance promotions hold main's version.** Catch-up work
(dependency bumps, CI/doc fixes, template re-syncs) reaches `main`
without releasing develop's leading minor via `git checkout main --
version.json` on the promotion branch (the pattern used for PlexCleaner
#734). A release promotion carries develop's version, after which
develop bumps again.
Written in current-state declarative voice. No CI enforcement
(documentation only).
Contributor
There was a problem hiding this comment.
Pull request overview
This PR promotes and aligns documentation about the repository's maintainer-controlled versioning policy across the primary contributor docs, emphasizing the "develop leads main by a minor" approach and the "maintenance promotions hold main's version" procedure.
Changes:
- Document that
version.json(major.minor) is a maintainer-edited version floor, with NBGV supplying git height as the patch position. - Describe the post-release workflow: after
develop -> mainreleases, bumpdevelop's minor via an isolatedbump-version-X.YPR to keep prereleases sorting abovemain's last stable. - Describe the maintenance-promotion workflow: keep
main's version by checking outversion.jsonfrommainwhen promoting maintenance-only changes.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| README.md | Adds a concise branching-model bullet describing the release vs. maintenance promotion versioning steps and links back to AGENTS.md. |
| AGENTS.md | Adds a dedicated, structured "Versioning is semantic and maintainer-controlled" section under Release Model, including develop-leads and maintenance-hold rules. |
| .github/copilot-instructions.md | Surfaces the same versioning workflow at the top-level Copilot instructions so agents inherit the policy in derived repos. |
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.
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).