threads / patch / 62146

patchBreakingChanges: early adopter option

Subject: [PATCH] BreakingChanges: early adopter option

## tl;dr

14 messages between Sep 19, 2024 and Mar 3, 2025. Diffs are folded; open one to read it.

replies: 13people: 4as markdown or json

Junio C Hamano· Sep 19, 2024, 19:33 UTC · lore

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@pobox.com>
---
 * 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(-)
Show changes to diff +22 −1
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
Junio C Hamano· Sep 20, 2024, 21:33 UTC · re: Junio C Hamano · lore

Re: [PATCH] BreakingChanges: early adopter option

Junio C Hamano <gitster@pobox.com> writes:
Show 17 quoted lines
> 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@pobox.com>
> ---
>
>  * 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.

So I was looking at my other topic that prepares to deprecate and remove core.preferSymlinkRefs configuration (i.e. we would still be able to work with a repository whose HEAD is a symbolic link pointing at refs/heads/main, but we would never be able to use a symbolic link to represent a symref ourselves, so "git checkout next" would replace HEAD with a textual symref, a file that has a single line "ref: refs/heads/next" in it), to see what it involves to allow early adopters to experience Git 3.0 features/removals before it actually happens.

Switching behaviour at runtime with feature.git3 should work well, and we can also add tests that checks the new behaviour by doing "test_config feature.git3 true".

One trouble is what to do with "git $cmd --help" for those who choose to be early adopters.

For "git $cmd --help" and "git -c feature.git3=true $cmd --help" to show documents describing the behaviour before and after Git 3.0 version boundary, we'd need to install separate set of documents and switch between them at runtime in builtin/help.c:setup_man_path() and friends [*]. If we are going to have such a transition often (e.g., more frequently than every few years), laying such an infrastructure would certainly be worth it, but an obvious alternative is to say that, even though the toggling of behaviour can be done at runtime to allow the early adopters from going back to the current behaviour to make their life less risky, the contents of the manual pages are defined at the compile time.

If we are willing to burden early adopters a bit more, we could make it a build-time option. With "make GIT_BUILD_FOR_GIT3=YesPlease", binaries will be built for all the then-current Git 3.0 features and documentation under development. It certainly is a simpler-to-build option that is easier for us, but I am not sure if that is acceptable by those who volunteer to test the upcoming big version.

One thing to note is that depending on the nature of a change, once you start using a feature only available in a newer version of Git in your repository, the resulting repository may not be understood by an older version of Git (imagine you started using index v4---now you are locked out of your repository if you want to go back to a version of Git before 1.7.11). So in that sense, it might be a disservice to promise that an early adopter can experience the future with feature.git3=on and then can safely go back to the current world by flipping it off, and we might be better off to control this with a single big red build-time switch.

Opinions?
[Footnote]
 * Alternatively we could tweak system_path() to hack the value we
   return when asked about GIT_INFO_PATH, GIT_MAN_PATH, and
   GIT_HTML_PATH, but I somehow feel dirty just for mentioning such
   an implementation possibility X-<.
Junio C Hamano· Sep 22, 2024, 17:51 UTC · re: Junio C Hamano · lore

Re: [PATCH] BreakingChanges: early adopter option

Junio C Hamano <gitster@pobox.com> writes:
Show 15 quoted lines
> Junio C Hamano <gitster@pobox.com> writes:
>
>> 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.
>> ...
> ... to see what it involves
> to allow early adopters to experience Git 3.0 features/removals
> before it actually happens.

Sorry for a long monologue on this important topic, while everybody is away. Hopefully we'll see more comments when they get back once the week starts ;-)

Show 15 quoted lines
> Switching behaviour at runtime with feature.git3 should work well,
> and we can also add tests that checks the new behaviour by doing
> "test_config feature.git3 true".
> ...
> If we are willing to burden early adopters a bit more, we could make
> it a build-time option.  With "make GIT_BUILD_FOR_GIT3=YesPlease",
> binaries will be built for all the then-current Git 3.0 features and
> documentation under development.  It certainly is a simpler-to-build
> option that is easier for us, but I am not sure if that is acceptable
> by those who volunteer to test the upcoming big version.
>
> One thing to note is that depending on the nature of a change, once
> you start using a feature only available in a newer version of Git
> in your repository, the resulting repository may not be understood
> by an older version of Git...

While I still am with the position that we can do this either at runtime or at build time, with the trade-off being that it is more costly for developers to do it at runtime and more cumbersome for early adopters to do it at build time, I realize that the last point above is unrelated. If one or some of the features behind either feature.git3 runtime option or GIT_BUILD_FOR_GIT3 build-time option makes a repository inaccessible to versions of Git without these features, we have the extension.* mechanism to make sure nothing breaks, and testing that such a Git3 feature is properly protected by the extension.* mechanism is part of the early adopter testing.

How much more costly to do at runtime is still subject to further analysis, I think. I know that it means we need to build and install the docs twice to support "git -c feature.git3=on help", for example, but I am not sure what the best way to use CI would be (write tests that check features with different behaviour by explicitly running them with "git -c feature.git3=on"? Run the same set of tests in a separate job that has "[feature] git3" in its $HOME/.gitconfig?).

Patrick Steinhardt· Sep 26, 2024, 11:57 UTC · re: Junio C Hamano · lore

Re: [PATCH] BreakingChanges: early adopter option

On Sun, Sep 22, 2024 at 10:51:52AM -0700, Junio C Hamano wrote:
Show 16 quoted lines
> Junio C Hamano <gitster@pobox.com> writes:
> > Junio C Hamano <gitster@pobox.com> writes:
> >
> >> 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.
> >> ...
> > ... to see what it involves
> > to allow early adopters to experience Git 3.0 features/removals
> > before it actually happens.

Thanks for putting together this document! We also had this discussion during the contributor's summit, and I certainly agree that having such a toggle makes a ton of sense.

Show 39 quoted lines
> Sorry for a long monologue on this important topic, while everybody
> is away.  Hopefully we'll see more comments when they get back once
> the week starts ;-)
> 
> > Switching behaviour at runtime with feature.git3 should work well,
> > and we can also add tests that checks the new behaviour by doing
> > "test_config feature.git3 true".
> > ...
> > If we are willing to burden early adopters a bit more, we could make
> > it a build-time option.  With "make GIT_BUILD_FOR_GIT3=YesPlease",
> > binaries will be built for all the then-current Git 3.0 features and
> > documentation under development.  It certainly is a simpler-to-build
> > option that is easier for us, but I am not sure if that is acceptable
> > by those who volunteer to test the upcoming big version.
> >
> > One thing to note is that depending on the nature of a change, once
> > you start using a feature only available in a newer version of Git
> > in your repository, the resulting repository may not be understood
> > by an older version of Git...
> 
> While I still am with the position that we can do this either at
> runtime or at build time, with the trade-off being that it is more
> costly for developers to do it at runtime and more cumbersome for
> early adopters to do it at build time, I realize that the last point
> above is unrelated.  If one or some of the features behind either
> feature.git3 runtime option or GIT_BUILD_FOR_GIT3 build-time option
> makes a repository inaccessible to versions of Git without these
> features, we have the extension.* mechanism to make sure nothing
> breaks, and testing that such a Git3 feature is properly protected
> by the extension.* mechanism is part of the early adopter testing.
> 
> How much more costly to do at runtime is still subject to further
> analysis, I think.  I know that it means we need to build and
> install the docs twice to support "git -c feature.git3=on help", for
> example, but I am not sure what the best way to use CI would be
> (write tests that check features with different behaviour by
> explicitly running them with "git -c feature.git3=on"?  Run the same
> set of tests in a separate job that has "[feature] git3" in its
> $HOME/.gitconfig?).

One problem with runtime toggles are commands that go away entirely. We can of course hide them away in various different places and make it impossible to call them. But one of the downsides is that it is not "true" to the actual removal, as for example the dashed builtins may still exist.

That makes me personally lean into the direction fo making this a build time knob. The big downside of course is that we'll have less exposure as almost nobody ever would build their Git in such a way. But the big upside is that we end up executing the code exactly as it would look like if it were removed, so the coverage we get e.g. both from Git devs and from our CI would be much more telling.

Patrick
Phillip Wood· Sep 26, 2024, 14:16 UTC · re: Patrick Steinhardt · lore

Re: [PATCH] BreakingChanges: early adopter option

On 26/09/2024 12:57, Patrick Steinhardt wrote:
Show 17 quoted lines
> On Sun, Sep 22, 2024 at 10:51:52AM -0700, Junio C Hamano wrote:
>> Junio C Hamano <gitster@pobox.com> writes:
>>> Junio C Hamano <gitster@pobox.com> writes:
>> How much more costly to do at runtime is still subject to further
>> analysis, I think.  I know that it means we need to build and
>> install the docs twice to support "git -c feature.git3=on help", for
>> example, but I am not sure what the best way to use CI would be
>> (write tests that check features with different behaviour by
>> explicitly running them with "git -c feature.git3=on"?  Run the same
>> set of tests in a separate job that has "[feature] git3" in its
>> $HOME/.gitconfig?).
> 
> One problem with runtime toggles are commands that go away entirely. We
> can of course hide them away in various different places and make it
> impossible to call them. But one of the downsides is that it is not
> "true" to the actual removal, as for example the dashed builtins may
> still exist.

We should be able to make sure those dashed builtins fail though, while that isn't exactly the same as the command not existing it would signal that the command does not work in git3.

> That makes me personally lean into the direction fo making this a build
> time knob.
That's certainly easier to implement.
> The big downside of course is that we'll have less exposure
> as almost nobody ever would build their Git in such a way.

Yes, it's hard to see many people doing that, though if we're lucky some companies that build their own git will test the git3 build. It's also hard to judge how many people would turn on the config option - if we go with that route we could be doing (a lot?) of extra work for not much benefit.

I remember the 1.0 to 2.0 transition as a user. I recall seeing advice massages describing the upcoming changes to "git add -u" and push.default before the 2.0 release. We should check if any of the proposed changes for 3.0 would benefit from something similar.

> But the big
> upside is that we end up executing the code exactly as it would look
> like if it were removed, so the coverage we get e.g. both from Git devs
> and from our CI would be much more telling.
Indeed
Best Wishes
Phillip
Junio C Hamano· Sep 26, 2024, 16:25 UTC · re: Phillip Wood · lore

Re: [PATCH] BreakingChanges: early adopter option

Phillip Wood <phillip.wood123@gmail.com> writes:
Show 10 quoted lines
>> One problem with runtime toggles are commands that go away
>> entirely. We
>> can of course hide them away in various different places and make it
>> impossible to call them. But one of the downsides is that it is not
>> "true" to the actual removal, as for example the dashed builtins may
>> still exist.
>
> We should be able to make sure those dashed builtins fail though,
> while that isn't exactly the same as the command not existing it would
> signal that the command does not work in git3.

Yes, that is what Patrick means by "we can of course hide" and what I meant by "it is more costly for developers to do it at runtime".

Show 5 quoted lines
> Yes, it's hard to see many people doing that, though if we're lucky
> some companies that build their own git will test the git3 build. It's
> also hard to judge how many people would turn on the config option -
> if we go with that route we could be doing (a lot?) of extra work for
> not much benefit.
That is certainly a thing worth considering.
Junio C Hamano· Sep 26, 2024, 16:26 UTC · re: Phillip Wood · lore

Re: [PATCH] BreakingChanges: early adopter option

Phillip Wood <phillip.wood123@gmail.com> writes:
Show 10 quoted lines
>> One problem with runtime toggles are commands that go away
>> entirely. We
>> can of course hide them away in various different places and make it
>> impossible to call them. But one of the downsides is that it is not
>> "true" to the actual removal, as for example the dashed builtins may
>> still exist.
>
> We should be able to make sure those dashed builtins fail though,
> while that isn't exactly the same as the command not existing it would
> signal that the command does not work in git3.

Yes, that is what Patrick means by "we can of course hide" and what I meant by "it is more costly for developers to do it at runtime".

Show 5 quoted lines
> Yes, it's hard to see many people doing that, though if we're lucky
> some companies that build their own git will test the git3 build. It's
> also hard to judge how many people would turn on the config option -
> if we go with that route we could be doing (a lot?) of extra work for
> not much benefit.
That is certainly a thing worth considering.
Thanks.
Junio C Hamano· Sep 26, 2024, 15:57 UTC · re: Patrick Steinhardt · lore

Re: [PATCH] BreakingChanges: early adopter option

Patrick Steinhardt <ps@pks.im> writes:
Show 14 quoted lines
>> How much more costly to do at runtime is still subject to further
>> analysis, I think.  I know that it means we need to build and
>> install the docs twice to support "git -c feature.git3=on help", for
>> example, but I am not sure what the best way to use CI would be
>> (write tests that check features with different behaviour by
>> explicitly running them with "git -c feature.git3=on"?  Run the same
>> set of tests in a separate job that has "[feature] git3" in its
>> $HOME/.gitconfig?).
>
> One problem with runtime toggles are commands that go away entirely. We
> can of course hide them away in various different places and make it
> impossible to call them. But one of the downsides is that it is not
> "true" to the actual removal, as for example the dashed builtins may
> still exist.

Yes, as I said, such a change to various infrastructure that are not specific to Git 3.0 boundary (e.g. run_builtin() dispatch needs to tell which new commands are from the future and hide them unless configured) is costly but reusable once written. A new or removed command that is not a built-in is even harder to manage at runtime.

Show 6 quoted lines
> That makes me personally lean into the direction fo making this a build
> time knob. The big downside of course is that we'll have less exposure
> as almost nobody ever would build their Git in such a way. But the big
> upside is that we end up executing the code exactly as it would look
> like if it were removed, so the coverage we get e.g. both from Git devs
> and from our CI would be much more telling.
Sad but I tend to agree.
Junio C Hamano· Oct 11, 2024, 21:49 UTC · re: Junio C Hamano · lore

[PATCH v2] 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>
---
 * As we discussed and came to agreement during the review of v1,
   let's specify this as a build-time knob.
 Documentation/BreakingChanges.txt | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)
Show changes to Documentation/BreakingChanges.txt +20 −1
diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index 2b64665694..eeb26c9155 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -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

Interdiff against v1:
  diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
  index cc19e03230..eeb26c9155 100644
  --- a/Documentation/BreakingChanges.txt
  +++ b/Documentation/BreakingChanges.txt
  @@ -68,15 +68,13 @@ 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.
  +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

-- 
2.47.0-150-gc349d40f0e
Patrick Steinhardt· Oct 16, 2024, 07:22 UTC · re: Junio C Hamano · lore

Re: [PATCH v2] BreakingChanges: early adopter option

On Fri, Oct 11, 2024 at 02:49:39PM -0700, Junio C Hamano wrote:
Show 25 quoted lines
> diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
> index 2b64665694..eeb26c9155 100644
> --- a/Documentation/BreakingChanges.txt
> +++ b/Documentation/BreakingChanges.txt
> @@ -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.
> +

Agreed. In fact, I'd even tighten the last part a bit: once we have any breaking changes queued in the tree, we MUST have a CI job that exercises things regularly.

Other than that this looks good to me, thanks!
Patrick
Taylor Blau· Oct 16, 2024, 22:07 UTC · re: Patrick Steinhardt · lore

Re: [PATCH v2] BreakingChanges: early adopter option

On Wed, Oct 16, 2024 at 09:22:13AM +0200, Patrick Steinhardt wrote:
Show 32 quoted lines
> On Fri, Oct 11, 2024 at 02:49:39PM -0700, Junio C Hamano wrote:
> > diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
> > index 2b64665694..eeb26c9155 100644
> > --- a/Documentation/BreakingChanges.txt
> > +++ b/Documentation/BreakingChanges.txt
> > @@ -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.
> > +
>
> Agreed. In fact, I'd even tighten the last part a bit: once we have any
> breaking changes queued in the tree, we MUST have a CI job that
> exercises things regularly.
>
> Other than that this looks good to me, thanks!
Thanks, both. Let's start merging this one down.

Thanks, Taylor

Junio C Hamano· Feb 28, 2025, 17:28 UTC · re: Taylor Blau · lore

Re* [PATCH v2] BreakingChanges: early adopter option

Junio C Hamano <gitster@pobox.com> writes:
Show 16 quoted lines
> +== 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.

So we decided to give up the runtime switching idea (which was what the v1 iteration of this patch proposed), and instead to change the behaviour at compile-time. One major part of this decision was to deal with documentation and other things that cannot be changed at the runtime with a feature.* configuration.

Show 6 quoted lines
>  == 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`.

Hence, we should strike the added sentence out of this hunk. But I forgot to do so when I prepared this v2.

We also discussed how to deal with irreversible changes to a repository that renders it unusable by the current crop of Git, once a such version of Git from the future touches it. Floated was an idea to put extensions.* mechanism to work for that purpose, but the resulting document does not have anything to say about it.

Which I think is perfectly fine, because such a "repository incompatibility change" should come with its own extensions.* mechanism to protect the resulting repository, whether such a change is part of the WITH_BREAKING_CHANGES feature set or not. It is not something the BreakingChanges document need to discuss.

So here is a small update to the text.
--- >8 ---
Subject: BreakingChanges: clarify the procedure

The point behind a compile-time switch is to ensure that we have a mechanism to hide myriad of backward incompatible changes that may be prepared and accumulated over time, yet make them available for testing any time during the development toward the big version boundary. Add a few words to stress that point.

Since the document was first written, we have added the CI job that the document anticipated us to have. Rephrase to state the current status.

The discussion in [*1*] made us abandon the "feature.git3" based runtime switching of behaviour and instead adopt the compile-time switching mechanism, but a stray sentence about runtime switching still remained in the final text by mistake. Remove it.

[Reference]
 *1* https://lore.kernel.org/git/xmqqldzel6ug.fsf@gitster.g/
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/BreakingChanges.adoc | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)
Show changes to diff +5 −6
diff --git c/Documentation/BreakingChanges.adoc w/Documentation/BreakingChanges.adoc
index 042709a461..bdfad29d8a 100644
--- c/Documentation/BreakingChanges.adoc
+++ w/Documentation/BreakingChanges.adoc
@@ -66,22 +66,21 @@ 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.
+be deployable trivially at such a version boundary, prepared over long
+time.
 
 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.
+boundary are already in effect.  We also have a CI job 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.  The early
-adopter configuration used for changes for this release is `feature.git3`.
+is no planned release date for this breaking version yet.
 
 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
Patrick Steinhardt· Mar 3, 2025, 10:30 UTC · re: Junio C Hamano · lore

Re: Re* [PATCH v2] BreakingChanges: early adopter option

On Fri, Feb 28, 2025 at 09:28:21AM -0800, Junio C Hamano wrote:
Show 59 quoted lines
> Junio C Hamano <gitster@pobox.com> writes:
> Subject: BreakingChanges: clarify the procedure
> 
> The point behind a compile-time switch is to ensure that we have a
> mechanism to hide myriad of backward incompatible changes that may
> be prepared and accumulated over time, yet make them available for
> testing any time during the development toward the big version
> boundary.  Add a few words to stress that point.
> 
> Since the document was first written, we have added the CI job that
> the document anticipated us to have.  Rephrase to state the current
> status.
> 
> The discussion in [*1*] made us abandon the "feature.git3" based
> runtime switching of behaviour and instead adopt the compile-time
> switching mechanism, but a stray sentence about runtime switching
> still remained in the final text by mistake.  Remove it.
> 
> [Reference]
> 
>  *1* https://lore.kernel.org/git/xmqqldzel6ug.fsf@gitster.g/
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/BreakingChanges.adoc | 11 +++++------
>  1 file changed, 5 insertions(+), 6 deletions(-)
> 
> diff --git c/Documentation/BreakingChanges.adoc w/Documentation/BreakingChanges.adoc
> index 042709a461..bdfad29d8a 100644
> --- c/Documentation/BreakingChanges.adoc
> +++ w/Documentation/BreakingChanges.adoc
> @@ -66,22 +66,21 @@ 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.
> +be deployable trivially at such a version boundary, prepared over long
> +time.
>  
>  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.
> +boundary are already in effect.  We also have a CI job 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.  The early
> -adopter configuration used for changes for this release is `feature.git3`.
> +is no planned release date for this breaking version yet.
>  
>  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
Thanks, the change look sensible to me.
Patrick
Junio C Hamano· Mar 3, 2025, 16:32 UTC · re: Patrick Steinhardt · lore

Re: Re* [PATCH v2] BreakingChanges: early adopter option

Patrick Steinhardt <ps@pks.im> writes:
>>  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
>
> Thanks, the change look sensible to me.
Thanks.

← back to recent threads