docs: record how VCell actually versions, and tag the verified commit - #2017
Merged
Conversation
The table described MINOR as "significant new feature" and MAJOR as a breaking change or public release event, which reads like semantic versioning. It is not how this project versions, and it invites a deliberation at every release cut that has one answer. Almost every VCell release is a PATCH, whatever it contains. MINOR marks a public release event -- a version announced to users, with its own narrative and vcell.org entry -- which is a decision about announcing rather than about the size of the change. MAJOR is for a very large new capability and is rare. A user-facing breaking change is called out in the release's Highlights paragraph; it does not by itself force a bump. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FUd61NUJgz88h4PZs5MqHn
…s now The script pins MASTER_SHA at the start and runs regression against it, then created the release with --target master. Anything merged in between -- the gate takes several minutes -- would be tagged and shipped without having been through regression, and the log would still show the pinned SHA as verified. Noticed while holding a docs merge during the 8.1.1.01 cut, precisely to avoid this. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FUd61NUJgz88h4PZs5MqHn
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.
1. Versioning
docs/RELEASING.mddescribedMINORas "significant new feature" andMAJORas "breaking change or public release event". That reads like semantic versioning, and it isn't how this project versions — it invites a deliberation at every release cut that has one answer.How VCell actually versions:
release-notes/major/narrative and vcell.org entrySo "cut a release" means a PATCH bump. A release is not held back from PATCH because it contains a feature, and does not earn a MINOR by containing one. MINOR is a decision about announcing, not about the size of the diff.
A user-facing breaking change is called out in the release's
Highlights.paragraph rather than forcing a bump.I got this wrong on #2015, where I reasoned about "why PATCH rather than MINOR" — the answer was never in doubt, the doc just implied it was.
2.
--target mastercould tag an unverified commitrelease-and-deploy.shpinsMASTER_SHAat the start and runs regression against it, then did:The regression gate takes several minutes. Anything merged in that window would be tagged and shipped without having been through regression — and the log would still show the pinned SHA as the verified one, so it would not look wrong.
Now
--target "$MASTER_SHA".Found concretely: this PR was written during the 8.1.1.01 cut and I held the merge until the tag existed, specifically because of this. The tag landed on
ad59f32ad4as intended.🤖 Generated with Claude Code
https://claude.ai/code/session_01FUd61NUJgz88h4PZs5MqHn