kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

BreakingChanges: early adopter option 

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.

Earlier we considered to guard the breaking changes with a run-time
check of the `feature.git<version>` configuration to allow brave
users and developers to opt into them as early adoptors.  But the
engineering cost to support such a run-time switch, covering new and
disappearing git subcommands and how "git help" would adjust the
documentation to the run-time switch, would be unrealistically high
to be worth it.

Formalize the mechanism based on a compile-time switch 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@pobox.com>
maint
Junio C Hamano 2024-10-11 14:49:39 -07:00
parent 6531f31ef3
commit 2454970930
1 changed files with 20 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
Documentation/BreakingChanges.txt
View File

@ -59,10 +59,29 @@ 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 a compile-time switch,
WITH_BREAKING_CHANGES, to help this process. When built with it,
the resulting Git binary together with its documentation would
behave as if these breaking changes slated for the next big version
boundary are already in effect. We may also want to have a CI job
or two to exercise the work-in-progress version of Git with these
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