[PATCH] BreakingChanges: early adopter option

[PATCH] BreakingChanges: early adopter option

[Junio C Hamano]

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(-)

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

Re: [PATCH] BreakingChanges: early adopter option

[Junio C Hamano]

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.
>
> 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-<.

Re: [PATCH] BreakingChanges: early adopter option

[Junio C Hamano]

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.

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?).

Re: [PATCH] BreakingChanges: early adopter option

[Patrick Steinhardt]

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:
> >
> >> 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.

> 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

Re: [PATCH] BreakingChanges: early adopter option

[Phillip Wood]

On 26/09/2024 12:57, Patrick Steinhardt wrote:
> 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

Re: [PATCH] BreakingChanges: early adopter option

[Junio C Hamano]

Phillip Wood <phillip.wood123@gmail.com> writes:

>> 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".

> 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.

Re: [PATCH] BreakingChanges: early adopter option

[Junio C Hamano]

Phillip Wood <phillip.wood123@gmail.com> writes:

>> 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".

> 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.

Re: [PATCH] BreakingChanges: early adopter option

[Junio C Hamano]

Patrick Steinhardt <ps@pks.im> 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.

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.

> 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.

[PATCH v2] BreakingChanges: early adopter option

[Junio C Hamano]

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(-)

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

Re: [PATCH v2] BreakingChanges: early adopter option

[Patrick Steinhardt]

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!

Patrick

Re: [PATCH v2] BreakingChanges: early adopter option

[Taylor Blau]

On Wed, Oct 16, 2024 at 09:22:13AM +0200, Patrick Steinhardt wrote:
> 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

Re* [PATCH v2] BreakingChanges: early adopter option

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> +== 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.

>  == 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(-)

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

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

[Patrick Steinhardt]

On Fri, Feb 28, 2025 at 09:28:21AM -0800, Junio C Hamano wrote:
> 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

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

[Junio C Hamano]

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.