Discussing the desire to make breaking changes, declaring that breaking changes are made at a certain version boundary, and recording these decisions in this document, are necessary but not sufficient. We need to make sure that we can implement, test, and deploy such impactful changes. Formalize the mechanism based on the `feature.*` configuration variable to allow early adopters to opt into the breaking change in a version of Git before the planned version for the breaking change. Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx> --- * Before I forget. I'll find time to rewrite the "we no longer honor core.preferSymlinkRefs" topic to follow this new guideline when we see a rough concensus that both the procedure outlined here and the idea to remove core.preferSymlinkRefs are good. Documentation/BreakingChanges.txt | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git i/Documentation/BreakingChanges.txt w/Documentation/BreakingChanges.txt index 2b64665694..9f1e9a0fb8 100644 --- i/Documentation/BreakingChanges.txt +++ w/Documentation/BreakingChanges.txt @@ -59,10 +59,31 @@ over time. If circumstances change, an earlier decision to deprecate or change something may need to be revisited from time to time. So do not take items on this list to mean "it is settled, do not waste our time bringing it up again". +== Procedure + +Discussing the desire to make breaking changes, declaring that breaking +changes are made at a certain version boundary, and recording these +decisions in this document, are necessary but not sufficient. +Because such changes are expected to be numerous, and the design and +implementation of them are expected to span over time, they have to +be deployable trivially at such a version boundary. + +The breaking changes MUST be guarded with the configuration +variable, `feature.git<version>` to help this process. Each +individual breaking change must be implemented in such a way that +for a user who has this configuration variable set to true, it goes +in effect even before Git <version>. Note that setting the +configuration to `false` MUST have no effect, either before or AFTER +Git <version>. In other words, this is purely an option to recruit +early adopters and not a mechanism to keep the old behaviour after +the announced version boundary for breaking changes. + + == Git 3.0 The following subsections document upcoming breaking changes for Git 3.0. There -is no planned release date for this breaking version yet. +is no planned release date for this breaking version yet. The early +adopter configuration used for changes for this release is `feature.git3`. Proposed changes and removals only include items which are "ready" to be done. In other words, this is not supposed to be a wishlist of features that should
