docs(releasing): document the pre-1.0 version mapping - #808
Draft
ajalon1 wants to merge 1 commit into
Draft
Conversation
releasing.md said a breaking command-line change takes a MAJOR bump, with no carve-out for `0.x`. Read literally that puts the next breaking release at v1.0.0, which is not the intent while the interface is still moving -- so the guidance gave no usable answer for the releases we actually cut. Add the pre-1.0 mapping (breaking to minor, features and fixes to patch, which is what v0.2.84 and v0.2.85 already shipped), and a short checklist for identifying a breaking change. The checklist calls out the case that is easiest to miss: a bug fix that tightens a previously permissive check still breaks whoever depended on the permissive behavior. Step 3 and best practice 5 both pointed at the old MAJOR rule; both now point at the pre-1.0 mapping.
ajalon1
changed the title
ajalon1
changed the title
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.
RATIONALE
While reviewing the
v0.2.86..maindiff to pick the next stable version, theversioning guidance in
releasing.mdturned out to give no usable answer.The doc says a breaking command-line change takes a MAJOR bump, and offers no
carve-out for
0.x. Read literally, the next release containing a breaking changeis
v1.0.0— which nobody intends while the interface is still moving. So theperson cutting the release has to either ignore the doc or freeze the CLI by
accident. Neither is good, and the answer shouldn't depend on who happens to be
doing the release that week.
This also matters right now: the current
maincontains a behavior change thatnarrows template detection (
repo.IsTemplateDirreplacing the old bare.datarobotcheck), which is exactly the kind of call this section should be ableto settle.
CHANGES
today: breaking → minor, features and fixes → patch. That is not a new policy,
it is what
v0.2.84andv0.2.85already shipped (both carriedfeatcommitsas patch releases).
force
v1.0.0, and thatv1.0.0should be a deliberate decision to freeze theCLI rather than a side effect of one breaking change.
share the patch slot pre-1.0, spotting the breaking change is the entire job of
step 3. The checklist includes the case that is easiest to miss: a bug fix that
tightens a previously permissive check still breaks whoever depended on the
permissive behavior.
Docs only — no code, no workflow changes.
NOTES
Open question for reviewers: the checklist treats "existing output changes shape"
as breaking, on the assumption that someone somewhere is parsing our stdout. If we
would rather scope that to
--output-format jsononly and treat human-readableoutput as unstable, say so and I will narrow it.
There is a pre-existing MD032 markdownlint warning further down this file (the
"To fix a failed release" list). Left alone to keep this diff focused.