{"thread":{"id":"62146","subject":"[PATCH] BreakingChanges: early adopter option","startedAt":"2024-09-19T19:33:50Z","lastAt":"2025-03-03T16:32:58Z","messageCount":14,"participants":["Junio C Hamano","Patrick Steinhardt","Phillip Wood","Taylor Blau"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"503089","messageId":"xmqq7cb77810.fsf@gitster.g","threadId":"62146","inReplyTo":null,"subject":"[PATCH] BreakingChanges: early adopter option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-19T19:33:47Z","receivedAt":"2024-09-19T19:33:50Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Discussing the desire to make breaking changes, declaring that\nbreaking changes are made at a certain version boundary, and\nrecording these decisions in this document, are necessary but not\nsufficient. We need to make sure that we can implement, test, and\ndeploy such impactful changes.\n\nFormalize the mechanism based on the `feature.*` configuration\nvariable to allow early adopters to opt into the breaking change in\na version of Git before the planned version for the breaking change.\n\nSigned-off-by: Junio C Hamano \n---\n\n * Before I forget. I'll find time to rewrite the \"we no longer\n honor core.preferSymlinkRefs\" topic to follow this new guideline\n when we see a rough concensus that both the procedure outlined\n here and the idea to remove core.preferSymlinkRefs are good.\n\n Documentation/BreakingChanges.txt | 23 ++++++++++++++++++++++-\n 1 file changed, 22 insertions(+), 1 deletion(-)\n\ndiff --git i/Documentation/BreakingChanges.txt w/Documentation/BreakingChanges.txt\nindex 2b64665694..9f1e9a0fb8 100644\n--- i/Documentation/BreakingChanges.txt\n+++ w/Documentation/BreakingChanges.txt\n@@ -59,10 +59,31 @@ over time. If circumstances change, an earlier decision to deprecate or change\n something may need to be revisited from time to time. So do not take items on\n this list to mean \"it is settled, do not waste our time bringing it up again\".\n \n+== Procedure\n+\n+Discussing the desire to make breaking changes, declaring that breaking\n+changes are made at a certain version boundary, and recording these\n+decisions in this document, are necessary but not sufficient.\n+Because such changes are expected to be numerous, and the design and\n+implementation of them are expected to span over time, they have to\n+be deployable trivially at such a version boundary.\n+\n+The breaking changes MUST be guarded with the configuration\n+variable, `feature.git` to help this process. Each\n+individual breaking change must be implemented in such a way that\n+for a user who has this configuration variable set to true, it goes\n+in effect even before Git . Note that setting the\n+configuration to `false` MUST have no effect, either before or AFTER\n+Git . In other words, this is purely an option to recruit\n+early adopters and not a mechanism to keep the old behaviour after\n+the announced version boundary for breaking changes.\n+\n+\n == Git 3.0\n \n The following subsections document upcoming breaking changes for Git 3.0. There\n-is no planned release date for this breaking version yet.\n+is no planned release date for this breaking version yet. The early\n+adopter configuration used for changes for this release is `feature.git3`.\n \n Proposed changes and removals only include items which are \"ready\" to be done.\n In other words, this is not supposed to be a wishlist of features that should\n"},{"id":"503166","messageId":"xmqqploydn7j.fsf@gitster.g","threadId":"62146","inReplyTo":"xmqq7cb77810.fsf@gitster.g","subject":"Re: [PATCH] BreakingChanges: early adopter option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-20T21:33:52Z","receivedAt":"2024-09-20T21:33:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Discussing the desire to make breaking changes, declaring that\n> breaking changes are made at a certain version boundary, and\n> recording these decisions in this document, are necessary but not\n> sufficient. We need to make sure that we can implement, test, and\n> deploy such impactful changes.\n>\n> Formalize the mechanism based on the `feature.*` configuration\n> variable to allow early adopters to opt into the breaking change in\n> a version of Git before the planned version for the breaking change.\n>\n> Signed-off-by: Junio C Hamano \n> ---\n>\n> * Before I forget. I'll find time to rewrite the \"we no longer\n> honor core.preferSymlinkRefs\" topic to follow this new guideline\n> when we see a rough concensus that both the procedure outlined\n> here and the idea to remove core.preferSymlinkRefs are good.\n\nSo I was looking at my other topic that prepares to deprecate and\nremove core.preferSymlinkRefs configuration (i.e. we would still be\nable to work with a repository whose HEAD is a symbolic link\npointing at refs/heads/main, but we would never be able to use a\nsymbolic link to represent a symref ourselves, so \"git checkout\nnext\" would replace HEAD with a textual symref, a file that has a\nsingle line \"ref: refs/heads/next\" in it), to see what it involves\nto allow early adopters to experience Git 3.0 features/removals\nbefore it actually happens.\n\nSwitching behaviour at runtime with feature.git3 should work well,\nand we can also add tests that checks the new behaviour by doing\n\"test_config feature.git3 true\".\n\nOne trouble is what to do with \"git $cmd --help\" for those who\nchoose to be early adopters.\n\nFor \"git $cmd --help\" and \"git -c feature.git3=true $cmd --help\" to\nshow documents describing the behaviour before and after Git 3.0\nversion boundary, we'd need to install separate set of documents and\nswitch between them at runtime in builtin/help.c:setup_man_path()\nand friends [*]. If we are going to have such a transition often\n(e.g., more frequently than every few years), laying such an\ninfrastructure would certainly be worth it, but an obvious\nalternative is to say that, even though the toggling of behaviour\ncan be done at runtime to allow the early adopters from going back\nto the current behaviour to make their life less risky, the contents\nof the manual pages are defined at the compile time.\n\nIf we are willing to burden early adopters a bit more, we could make\nit a build-time option. With \"make GIT_BUILD_FOR_GIT3=YesPlease\",\nbinaries will be built for all the then-current Git 3.0 features and\ndocumentation under development. It certainly is a simpler-to-build\noption that is easier for us, but I am not sure if that is acceptable\nby those who volunteer to test the upcoming big version.\n\nOne thing to note is that depending on the nature of a change, once\nyou start using a feature only available in a newer version of Git\nin your repository, the resulting repository may not be understood\nby an older version of Git (imagine you started using index v4---now\nyou are locked out of your repository if you want to go back to a\nversion of Git before 1.7.11). So in that sense, it might be a\ndisservice to promise that an early adopter can experience the\nfuture with feature.git3=on and then can safely go back to the\ncurrent world by flipping it off, and we might be better off to\ncontrol this with a single big red build-time switch.\n\nOpinions?\n\n\n[Footnote]\n\n * Alternatively we could tweak system_path() to hack the value we\n return when asked about GIT_INFO_PATH, GIT_MAN_PATH, and\n GIT_HTML_PATH, but I somehow feel dirty just for mentioning such\n an implementation possibility X-<.\n"},{"id":"503223","messageId":"xmqqtte77f0n.fsf@gitster.g","threadId":"62146","inReplyTo":"xmqqploydn7j.fsf@gitster.g","subject":"Re: [PATCH] BreakingChanges: early adopter option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-22T17:51:52Z","receivedAt":"2024-09-22T17:51:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Junio C Hamano writes:\n>\n>> Discussing the desire to make breaking changes, declaring that\n>> breaking changes are made at a certain version boundary, and\n>> recording these decisions in this document, are necessary but not\n>> sufficient. We need to make sure that we can implement, test, and\n>> deploy such impactful changes.\n>>\n>> Formalize the mechanism based on the `feature.*` configuration\n>> variable to allow early adopters to opt into the breaking change in\n>> a version of Git before the planned version for the breaking change.\n>> ...\n> ... to see what it involves\n> to allow early adopters to experience Git 3.0 features/removals\n> before it actually happens.\n\nSorry for a long monologue on this important topic, while everybody\nis away. Hopefully we'll see more comments when they get back once\nthe week starts ;-)\n\n> Switching behaviour at runtime with feature.git3 should work well,\n> and we can also add tests that checks the new behaviour by doing\n> \"test_config feature.git3 true\".\n> ...\n> If we are willing to burden early adopters a bit more, we could make\n> it a build-time option. With \"make GIT_BUILD_FOR_GIT3=YesPlease\",\n> binaries will be built for all the then-current Git 3.0 features and\n> documentation under development. It certainly is a simpler-to-build\n> option that is easier for us, but I am not sure if that is acceptable\n> by those who volunteer to test the upcoming big version.\n>\n> One thing to note is that depending on the nature of a change, once\n> you start using a feature only available in a newer version of Git\n> in your repository, the resulting repository may not be understood\n> by an older version of Git...\n\nWhile I still am with the position that we can do this either at\nruntime or at build time, with the trade-off being that it is more\ncostly for developers to do it at runtime and more cumbersome for\nearly adopters to do it at build time, I realize that the last point\nabove is unrelated. If one or some of the features behind either\nfeature.git3 runtime option or GIT_BUILD_FOR_GIT3 build-time option\nmakes a repository inaccessible to versions of Git without these\nfeatures, we have the extension.* mechanism to make sure nothing\nbreaks, and testing that such a Git3 feature is properly protected\nby the extension.* mechanism is part of the early adopter testing.\n\nHow much more costly to do at runtime is still subject to further\nanalysis, I think. I know that it means we need to build and\ninstall the docs twice to support \"git -c feature.git3=on help\", for\nexample, but I am not sure what the best way to use CI would be\n(write tests that check features with different behaviour by\nexplicitly running them with \"git -c feature.git3=on\"? Run the same\nset of tests in a separate job that has \"[feature] git3\" in its\n$HOME/.gitconfig?).\n"},{"id":"503538","messageId":"ZvVMNMiyjd4xfHzY@pks.im","threadId":"62146","inReplyTo":"xmqqtte77f0n.fsf@gitster.g","subject":"Re: [PATCH] BreakingChanges: early adopter option","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-09-26T11:57:52Z","receivedAt":"2024-09-26T11:57:59Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Sun, Sep 22, 2024 at 10:51:52AM -0700, Junio C Hamano wrote:\n> Junio C Hamano writes:\n> > Junio C Hamano writes:\n> >\n> >> Discussing the desire to make breaking changes, declaring that\n> >> breaking changes are made at a certain version boundary, and\n> >> recording these decisions in this document, are necessary but not\n> >> sufficient. We need to make sure that we can implement, test, and\n> >> deploy such impactful changes.\n> >>\n> >> Formalize the mechanism based on the `feature.*` configuration\n> >> variable to allow early adopters to opt into the breaking change in\n> >> a version of Git before the planned version for the breaking change.\n> >> ...\n> > ... to see what it involves\n> > to allow early adopters to experience Git 3.0 features/removals\n> > before it actually happens.\n\nThanks for putting together this document! We also had this discussion\nduring the contributor's summit, and I certainly agree that having such\na toggle makes a ton of sense.\n\n> Sorry for a long monologue on this important topic, while everybody\n> is away. Hopefully we'll see more comments when they get back once\n> the week starts ;-)\n> \n> > Switching behaviour at runtime with feature.git3 should work well,\n> > and we can also add tests that checks the new behaviour by doing\n> > \"test_config feature.git3 true\".\n> > ...\n> > If we are willing to burden early adopters a bit more, we could make\n> > it a build-time option. With \"make GIT_BUILD_FOR_GIT3=YesPlease\",\n> > binaries will be built for all the then-current Git 3.0 features and\n> > documentation under development. It certainly is a simpler-to-build\n> > option that is easier for us, but I am not sure if that is acceptable\n> > by those who volunteer to test the upcoming big version.\n> >\n> > One thing to note is that depending on the nature of a change, once\n> > you start using a feature only available in a newer version of Git\n> > in your repository, the resulting repository may not be understood\n> > by an older version of Git...\n> \n> While I still am with the position that we can do this either at\n> runtime or at build time, with the trade-off being that it is more\n> costly for developers to do it at runtime and more cumbersome for\n> early adopters to do it at build time, I realize that the last point\n> above is unrelated. If one or some of the features behind either\n> feature.git3 runtime option or GIT_BUILD_FOR_GIT3 build-time option\n> makes a repository inaccessible to versions of Git without these\n> features, we have the extension.* mechanism to make sure nothing\n> breaks, and testing that such a Git3 feature is properly protected\n> by the extension.* mechanism is part of the early adopter testing.\n> \n> How much more costly to do at runtime is still subject to further\n> analysis, I think. I know that it means we need to build and\n> install the docs twice to support \"git -c feature.git3=on help\", for\n> example, but I am not sure what the best way to use CI would be\n> (write tests that check features with different behaviour by\n> explicitly running them with \"git -c feature.git3=on\"? Run the same\n> set of tests in a separate job that has \"[feature] git3\" in its\n> $HOME/.gitconfig?).\n\nOne problem with runtime toggles are commands that go away entirely. We\ncan of course hide them away in various different places and make it\nimpossible to call them. But one of the downsides is that it is not\n\"true\" to the actual removal, as for example the dashed builtins may\nstill exist.\n\nThat makes me personally lean into the direction fo making this a build\ntime knob. The big downside of course is that we'll have less exposure\nas almost nobody ever would build their Git in such a way. But the big\nupside is that we end up executing the code exactly as it would look\nlike if it were removed, so the coverage we get e.g. both from Git devs\nand from our CI would be much more telling.\n\nPatrick\n"},{"id":"503556","messageId":"02d7b805-f006-43ca-906e-fe9398b8ec35@gmail.com","threadId":"62146","inReplyTo":"ZvVMNMiyjd4xfHzY@pks.im","subject":"Re: [PATCH] BreakingChanges: early adopter option","fromName":"Phillip Wood","fromEmail":"phillip.wood123@gmail.com","sentAt":"2024-09-26T14:16:09Z","receivedAt":"2024-09-26T14:16:13Z","isPatch":true,"sender":{"key":"phillip.wood@dunelm.org.uk","avatar":null},"body":"On 26/09/2024 12:57, Patrick Steinhardt wrote:\n> On Sun, Sep 22, 2024 at 10:51:52AM -0700, Junio C Hamano wrote:\n>> Junio C Hamano writes:\n>>> Junio C Hamano writes:\n>> How much more costly to do at runtime is still subject to further\n>> analysis, I think. I know that it means we need to build and\n>> install the docs twice to support \"git -c feature.git3=on help\", for\n>> example, but I am not sure what the best way to use CI would be\n>> (write tests that check features with different behaviour by\n>> explicitly running them with \"git -c feature.git3=on\"? Run the same\n>> set of tests in a separate job that has \"[feature] git3\" in its\n>> $HOME/.gitconfig?).\n> \n> One problem with runtime toggles are commands that go away entirely. We\n> can of course hide them away in various different places and make it\n> impossible to call them. But one of the downsides is that it is not\n> \"true\" to the actual removal, as for example the dashed builtins may\n> still exist.\n\nWe should be able to make sure those dashed builtins fail though, while \nthat isn't exactly the same as the command not existing it would signal \nthat the command does not work in git3.\n\n> That makes me personally lean into the direction fo making this a build\n> time knob.\n\nThat's certainly easier to implement.\n\n> The big downside of course is that we'll have less exposure\n> as almost nobody ever would build their Git in such a way.\n\nYes, it's hard to see many people doing that, though if we're lucky some \ncompanies that build their own git will test the git3 build. It's also \nhard to judge how many people would turn on the config option - if we go \nwith that route we could be doing (a lot?) of extra work for not much \nbenefit.\n\nI remember the 1.0 to 2.0 transition as a user. I recall seeing advice \nmassages describing the upcoming changes to \"git add -u\" and \npush.default before the 2.0 release. We should check if any of the \nproposed changes for 3.0 would benefit from something similar.\n\n> But the big\n> upside is that we end up executing the code exactly as it would look\n> like if it were removed, so the coverage we get e.g. both from Git devs\n> and from our CI would be much more telling.\n\nIndeed\n\nBest Wishes\n\nPhillip\n\n"},{"id":"503571","messageId":"xmqqed56mmqf.fsf@gitster.g","threadId":"62146","inReplyTo":"ZvVMNMiyjd4xfHzY@pks.im","subject":"Re: [PATCH] BreakingChanges: early adopter option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-26T15:57:28Z","receivedAt":"2024-09-26T15:57:30Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n>> How much more costly to do at runtime is still subject to further\n>> analysis, I think. I know that it means we need to build and\n>> install the docs twice to support \"git -c feature.git3=on help\", for\n>> example, but I am not sure what the best way to use CI would be\n>> (write tests that check features with different behaviour by\n>> explicitly running them with \"git -c feature.git3=on\"? Run the same\n>> set of tests in a separate job that has \"[feature] git3\" in its\n>> $HOME/.gitconfig?).\n>\n> One problem with runtime toggles are commands that go away entirely. We\n> can of course hide them away in various different places and make it\n> impossible to call them. But one of the downsides is that it is not\n> \"true\" to the actual removal, as for example the dashed builtins may\n> still exist.\n\nYes, as I said, such a change to various infrastructure that are not\nspecific to Git 3.0 boundary (e.g. run_builtin() dispatch needs to\ntell which new commands are from the future and hide them unless\nconfigured) is costly but reusable once written. A new or removed\ncommand that is not a built-in is even harder to manage at runtime.\n\n> That makes me personally lean into the direction fo making this a build\n> time knob. The big downside of course is that we'll have less exposure\n> as almost nobody ever would build their Git in such a way. But the big\n> upside is that we end up executing the code exactly as it would look\n> like if it were removed, so the coverage we get e.g. both from Git devs\n> and from our CI would be much more telling.\n\nSad but I tend to agree.\n"},{"id":"503575","messageId":"xmqqldzel6ug.fsf@gitster.g","threadId":"62146","inReplyTo":"02d7b805-f006-43ca-906e-fe9398b8ec35@gmail.com","subject":"Re: [PATCH] BreakingChanges: early adopter option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-26T16:25:59Z","receivedAt":"2024-09-26T16:26:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Phillip Wood writes:\n\n>> One problem with runtime toggles are commands that go away\n>> entirely. We\n>> can of course hide them away in various different places and make it\n>> impossible to call them. But one of the downsides is that it is not\n>> \"true\" to the actual removal, as for example the dashed builtins may\n>> still exist.\n>\n> We should be able to make sure those dashed builtins fail though,\n> while that isn't exactly the same as the command not existing it would\n> signal that the command does not work in git3.\n\nYes, that is what Patrick means by \"we can of course hide\" and what\nI meant by \"it is more costly for developers to do it at runtime\".\n\n> Yes, it's hard to see many people doing that, though if we're lucky\n> some companies that build their own git will test the git3 build. It's\n> also hard to judge how many people would turn on the config option -\n> if we go with that route we could be doing (a lot?) of extra work for\n> not much benefit.\n\nThat is certainly a thing worth considering.\n\n"},{"id":"503576","messageId":"xmqqjzeyl6ub.fsf@gitster.g","threadId":"62146","inReplyTo":"02d7b805-f006-43ca-906e-fe9398b8ec35@gmail.com","subject":"Re: [PATCH] BreakingChanges: early adopter option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-09-26T16:26:04Z","receivedAt":"2024-09-26T16:26:05Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Phillip Wood writes:\n\n>> One problem with runtime toggles are commands that go away\n>> entirely. We\n>> can of course hide them away in various different places and make it\n>> impossible to call them. But one of the downsides is that it is not\n>> \"true\" to the actual removal, as for example the dashed builtins may\n>> still exist.\n>\n> We should be able to make sure those dashed builtins fail though,\n> while that isn't exactly the same as the command not existing it would\n> signal that the command does not work in git3.\n\nYes, that is what Patrick means by \"we can of course hide\" and what\nI meant by \"it is more costly for developers to do it at runtime\".\n\n> Yes, it's hard to see many people doing that, though if we're lucky\n> some companies that build their own git will test the git3 build. It's\n> also hard to judge how many people would turn on the config option -\n> if we go with that route we could be doing (a lot?) of extra work for\n> not much benefit.\n\nThat is certainly a thing worth considering.\n\nThanks.\n"},{"id":"504884","messageId":"xmqq1q0mcnt8.fsf@gitster.g","threadId":"62146","inReplyTo":"xmqq7cb77810.fsf@gitster.g","subject":"[PATCH v2] BreakingChanges: early adopter option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2024-10-11T21:49:39Z","receivedAt":"2024-10-11T21:49:41Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Discussing the desire to make breaking changes, declaring that\nbreaking changes are made at a certain version boundary, and\nrecording these decisions in this document, are necessary but not\nsufficient. We need to make sure that we can implement, test, and\ndeploy such impactful changes.\n\nEarlier we considered to guard the breaking changes with a run-time\ncheck of the `feature.git` configuration to allow brave\nusers and developers to opt into them as early adoptors. But the\nengineering cost to support such a run-time switch, covering new and\ndisappearing git subcommands and how \"git help\" would adjust the\ndocumentation to the run-time switch, would be unrealistically high\nto be worth it.\n\nFormalize the mechanism based on a compile-time switch to allow\nearly adopters to opt into the breaking change in a version of Git\nbefore the planned version for the breaking change.\n\nSigned-off-by: Junio C Hamano \n---\n\n * As we discussed and came to agreement during the review of v1,\n let's specify this as a build-time knob.\n\n Documentation/BreakingChanges.txt | 21 ++++++++++++++++++++-\n 1 file changed, 20 insertions(+), 1 deletion(-)\n\ndiff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\nindex 2b64665694..eeb26c9155 100644\n--- a/Documentation/BreakingChanges.txt\n+++ b/Documentation/BreakingChanges.txt\n@@ -59,10 +59,29 @@ over time. If circumstances change, an earlier decision to deprecate or change\n something may need to be revisited from time to time. So do not take items on\n this list to mean \"it is settled, do not waste our time bringing it up again\".\n \n+== Procedure\n+\n+Discussing the desire to make breaking changes, declaring that breaking\n+changes are made at a certain version boundary, and recording these\n+decisions in this document, are necessary but not sufficient.\n+Because such changes are expected to be numerous, and the design and\n+implementation of them are expected to span over time, they have to\n+be deployable trivially at such a version boundary.\n+\n+The breaking changes MUST be guarded with the a compile-time switch,\n+WITH_BREAKING_CHANGES, to help this process. When built with it,\n+the resulting Git binary together with its documentation would\n+behave as if these breaking changes slated for the next big version\n+boundary are already in effect. We may also want to have a CI job\n+or two to exercise the work-in-progress version of Git with these\n+breaking changes.\n+\n+\n == Git 3.0\n \n The following subsections document upcoming breaking changes for Git 3.0. There\n-is no planned release date for this breaking version yet.\n+is no planned release date for this breaking version yet. The early\n+adopter configuration used for changes for this release is `feature.git3`.\n \n Proposed changes and removals only include items which are \"ready\" to be done.\n In other words, this is not supposed to be a wishlist of features that should\n\nInterdiff against v1:\n diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\n index cc19e03230..eeb26c9155 100644\n --- a/Documentation/BreakingChanges.txt\n +++ b/Documentation/BreakingChanges.txt\n @@ -68,15 +68,13 @@ Because such changes are expected to be numerous, and the design and\n implementation of them are expected to span over time, they have to\n be deployable trivially at such a version boundary.\n \n -The breaking changes MUST be guarded with the configuration\n -variable, `feature.git` to help this process. Each\n -individual breaking change must be implemented in such a way that\n -for a user who has this configuration variable set to true, it goes\n -in effect even before Git . Note that setting the\n -configuration to `false` MUST have no effect, either before or AFTER\n -Git . In other words, this is purely an option to recruit\n -early adopters and not a mechanism to keep the old behaviour after\n -the announced version boundary for breaking changes.\n +The breaking changes MUST be guarded with the a compile-time switch,\n +WITH_BREAKING_CHANGES, to help this process. When built with it,\n +the resulting Git binary together with its documentation would\n +behave as if these breaking changes slated for the next big version\n +boundary are already in effect. We may also want to have a CI job\n +or two to exercise the work-in-progress version of Git with these\n +breaking changes.\n \n \n == Git 3.0\n-- \n2.47.0-150-gc349d40f0e\n\n"},{"id":"505238","messageId":"Zw9ppbrFqVN5S50J@pks.im","threadId":"62146","inReplyTo":"xmqq1q0mcnt8.fsf@gitster.g","subject":"Re: [PATCH v2] BreakingChanges: early adopter option","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2024-10-16T07:22:13Z","receivedAt":"2024-10-16T07:22:20Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, Oct 11, 2024 at 02:49:39PM -0700, Junio C Hamano wrote:\n> diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\n> index 2b64665694..eeb26c9155 100644\n> --- a/Documentation/BreakingChanges.txt\n> +++ b/Documentation/BreakingChanges.txt\n> @@ -59,10 +59,29 @@ over time. If circumstances change, an earlier decision to deprecate or change\n> something may need to be revisited from time to time. So do not take items on\n> this list to mean \"it is settled, do not waste our time bringing it up again\".\n> \n> +== Procedure\n> +\n> +Discussing the desire to make breaking changes, declaring that breaking\n> +changes are made at a certain version boundary, and recording these\n> +decisions in this document, are necessary but not sufficient.\n> +Because such changes are expected to be numerous, and the design and\n> +implementation of them are expected to span over time, they have to\n> +be deployable trivially at such a version boundary.\n> +\n> +The breaking changes MUST be guarded with the a compile-time switch,\n> +WITH_BREAKING_CHANGES, to help this process. When built with it,\n> +the resulting Git binary together with its documentation would\n> +behave as if these breaking changes slated for the next big version\n> +boundary are already in effect. We may also want to have a CI job\n> +or two to exercise the work-in-progress version of Git with these\n> +breaking changes.\n> +\n\nAgreed. In fact, I'd even tighten the last part a bit: once we have any\nbreaking changes queued in the tree, we MUST have a CI job that\nexercises things regularly.\n\nOther than that this looks good to me, thanks!\n\nPatrick\n"},{"id":"505315","messageId":"ZxA5OWL1AuQxA/NC@nand.local","threadId":"62146","inReplyTo":"Zw9ppbrFqVN5S50J@pks.im","subject":"Re: [PATCH v2] BreakingChanges: early adopter option","fromName":"Taylor Blau","fromEmail":"me@ttaylorr.com","sentAt":"2024-10-16T22:07:53Z","receivedAt":"2024-10-16T22:07:57Z","isPatch":true,"sender":{"key":"me@ttaylorr.com","avatar":"https://avatars.githubusercontent.com/u/301000140?v=4"},"body":"On Wed, Oct 16, 2024 at 09:22:13AM +0200, Patrick Steinhardt wrote:\n> On Fri, Oct 11, 2024 at 02:49:39PM -0700, Junio C Hamano wrote:\n> > diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt\n> > index 2b64665694..eeb26c9155 100644\n> > --- a/Documentation/BreakingChanges.txt\n> > +++ b/Documentation/BreakingChanges.txt\n> > @@ -59,10 +59,29 @@ over time. If circumstances change, an earlier decision to deprecate or change\n> > something may need to be revisited from time to time. So do not take items on\n> > this list to mean \"it is settled, do not waste our time bringing it up again\".\n> >\n> > +== Procedure\n> > +\n> > +Discussing the desire to make breaking changes, declaring that breaking\n> > +changes are made at a certain version boundary, and recording these\n> > +decisions in this document, are necessary but not sufficient.\n> > +Because such changes are expected to be numerous, and the design and\n> > +implementation of them are expected to span over time, they have to\n> > +be deployable trivially at such a version boundary.\n> > +\n> > +The breaking changes MUST be guarded with the a compile-time switch,\n> > +WITH_BREAKING_CHANGES, to help this process. When built with it,\n> > +the resulting Git binary together with its documentation would\n> > +behave as if these breaking changes slated for the next big version\n> > +boundary are already in effect. We may also want to have a CI job\n> > +or two to exercise the work-in-progress version of Git with these\n> > +breaking changes.\n> > +\n>\n> Agreed. In fact, I'd even tighten the last part a bit: once we have any\n> breaking changes queued in the tree, we MUST have a CI job that\n> exercises things regularly.\n>\n> Other than that this looks good to me, thanks!\n\nThanks, both. Let's start merging this one down.\n\nThanks,\nTaylor\n"},{"id":"513289","messageId":"xmqqv7su2d3e.fsf_-_@gitster.g","threadId":"62146","inReplyTo":"ZxA5OWL1AuQxA/NC@nand.local","subject":"Re* [PATCH v2] BreakingChanges: early adopter option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-02-28T17:28:21Z","receivedAt":"2025-02-28T17:28:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> +== Procedure\n> +\n> +Discussing the desire to make breaking changes, declaring that breaking\n> +changes are made at a certain version boundary, and recording these\n> +decisions in this document, are necessary but not sufficient.\n> +Because such changes are expected to be numerous, and the design and\n> +implementation of them are expected to span over time, they have to\n> +be deployable trivially at such a version boundary.\n> +\n> +The breaking changes MUST be guarded with the a compile-time switch,\n> +WITH_BREAKING_CHANGES, to help this process. When built with it,\n> +the resulting Git binary together with its documentation would\n> +behave as if these breaking changes slated for the next big version\n> +boundary are already in effect. We may also want to have a CI job\n> +or two to exercise the work-in-progress version of Git with these\n> +breaking changes.\n\nSo we decided to give up the runtime switching idea (which was what\nthe v1 iteration of this patch proposed), and instead to change the\nbehaviour at compile-time. One major part of this decision was to\ndeal with documentation and other things that cannot be changed at\nthe runtime with a feature.* configuration.\n\n> == Git 3.0\n> \n> The following subsections document upcoming breaking changes for Git 3.0. There\n> -is no planned release date for this breaking version yet.\n> +is no planned release date for this breaking version yet. The early\n> +adopter configuration used for changes for this release is `feature.git3`.\n\nHence, we should strike the added sentence out of this hunk. But I\nforgot to do so when I prepared this v2.\n\nWe also discussed how to deal with irreversible changes to a\nrepository that renders it unusable by the current crop of Git, once\na such version of Git from the future touches it. Floated was an\nidea to put extensions.* mechanism to work for that purpose, but the\nresulting document does not have anything to say about it.\n\nWhich I think is perfectly fine, because such a \"repository\nincompatibility change\" should come with its own extensions.*\nmechanism to protect the resulting repository, whether such a change\nis part of the WITH_BREAKING_CHANGES feature set or not. It is not\nsomething the BreakingChanges document need to discuss.\n\nSo here is a small update to the text.\n\n--- >8 ---\nSubject: BreakingChanges: clarify the procedure\n\nThe point behind a compile-time switch is to ensure that we have a\nmechanism to hide myriad of backward incompatible changes that may\nbe prepared and accumulated over time, yet make them available for\ntesting any time during the development toward the big version\nboundary. Add a few words to stress that point.\n\nSince the document was first written, we have added the CI job that\nthe document anticipated us to have. Rephrase to state the current\nstatus.\n\nThe discussion in [*1*] made us abandon the \"feature.git3\" based\nruntime switching of behaviour and instead adopt the compile-time\nswitching mechanism, but a stray sentence about runtime switching\nstill remained in the final text by mistake. Remove it.\n\n[Reference]\n\n *1* https://lore.kernel.org/git/xmqqldzel6ug.fsf@gitster.g/\n\nSigned-off-by: Junio C Hamano \n---\n Documentation/BreakingChanges.adoc | 11 +++++------\n 1 file changed, 5 insertions(+), 6 deletions(-)\n\ndiff --git c/Documentation/BreakingChanges.adoc w/Documentation/BreakingChanges.adoc\nindex 042709a461..bdfad29d8a 100644\n--- c/Documentation/BreakingChanges.adoc\n+++ w/Documentation/BreakingChanges.adoc\n@@ -66,22 +66,21 @@ changes are made at a certain version boundary, and recording these\n decisions in this document, are necessary but not sufficient.\n Because such changes are expected to be numerous, and the design and\n implementation of them are expected to span over time, they have to\n-be deployable trivially at such a version boundary.\n+be deployable trivially at such a version boundary, prepared over long\n+time.\n \n The breaking changes MUST be guarded with the a compile-time switch,\n WITH_BREAKING_CHANGES, to help this process. When built with it,\n the resulting Git binary together with its documentation would\n behave as if these breaking changes slated for the next big version\n-boundary are already in effect. We may also want to have a CI job\n-or two to exercise the work-in-progress version of Git with these\n-breaking changes.\n+boundary are already in effect. We also have a CI job to exercise\n+the work-in-progress version of Git with these breaking changes.\n \n \n == Git 3.0\n \n The following subsections document upcoming breaking changes for Git 3.0. There\n-is no planned release date for this breaking version yet. The early\n-adopter configuration used for changes for this release is `feature.git3`.\n+is no planned release date for this breaking version yet.\n \n Proposed changes and removals only include items which are \"ready\" to be done.\n In other words, this is not supposed to be a wishlist of features that should\n"},{"id":"513394","messageId":"Z8WE0SK5QS4aVyYr@pks.im","threadId":"62146","inReplyTo":"xmqqv7su2d3e.fsf_-_@gitster.g","subject":"Re: Re* [PATCH v2] BreakingChanges: early adopter option","fromName":"Patrick Steinhardt","fromEmail":"ps@pks.im","sentAt":"2025-03-03T10:30:41Z","receivedAt":"2025-03-03T10:30:45Z","isPatch":true,"sender":{"key":"ps@pks.im","avatar":"https://avatars.githubusercontent.com/u/4056630?v=4"},"body":"On Fri, Feb 28, 2025 at 09:28:21AM -0800, Junio C Hamano wrote:\n> Junio C Hamano writes:\n> Subject: BreakingChanges: clarify the procedure\n> \n> The point behind a compile-time switch is to ensure that we have a\n> mechanism to hide myriad of backward incompatible changes that may\n> be prepared and accumulated over time, yet make them available for\n> testing any time during the development toward the big version\n> boundary. Add a few words to stress that point.\n> \n> Since the document was first written, we have added the CI job that\n> the document anticipated us to have. Rephrase to state the current\n> status.\n> \n> The discussion in [*1*] made us abandon the \"feature.git3\" based\n> runtime switching of behaviour and instead adopt the compile-time\n> switching mechanism, but a stray sentence about runtime switching\n> still remained in the final text by mistake. Remove it.\n> \n> [Reference]\n> \n> *1* https://lore.kernel.org/git/xmqqldzel6ug.fsf@gitster.g/\n> \n> Signed-off-by: Junio C Hamano \n> ---\n> Documentation/BreakingChanges.adoc | 11 +++++------\n> 1 file changed, 5 insertions(+), 6 deletions(-)\n> \n> diff --git c/Documentation/BreakingChanges.adoc w/Documentation/BreakingChanges.adoc\n> index 042709a461..bdfad29d8a 100644\n> --- c/Documentation/BreakingChanges.adoc\n> +++ w/Documentation/BreakingChanges.adoc\n> @@ -66,22 +66,21 @@ changes are made at a certain version boundary, and recording these\n> decisions in this document, are necessary but not sufficient.\n> Because such changes are expected to be numerous, and the design and\n> implementation of them are expected to span over time, they have to\n> -be deployable trivially at such a version boundary.\n> +be deployable trivially at such a version boundary, prepared over long\n> +time.\n> \n> The breaking changes MUST be guarded with the a compile-time switch,\n> WITH_BREAKING_CHANGES, to help this process. When built with it,\n> the resulting Git binary together with its documentation would\n> behave as if these breaking changes slated for the next big version\n> -boundary are already in effect. We may also want to have a CI job\n> -or two to exercise the work-in-progress version of Git with these\n> -breaking changes.\n> +boundary are already in effect. We also have a CI job to exercise\n> +the work-in-progress version of Git with these breaking changes.\n> \n> \n> == Git 3.0\n> \n> The following subsections document upcoming breaking changes for Git 3.0. There\n> -is no planned release date for this breaking version yet. The early\n> -adopter configuration used for changes for this release is `feature.git3`.\n> +is no planned release date for this breaking version yet.\n> \n> Proposed changes and removals only include items which are \"ready\" to be done.\n> In other words, this is not supposed to be a wishlist of features that should\n\nThanks, the change look sensible to me.\n\nPatrick\n"},{"id":"513411","messageId":"xmqq34fuxefc.fsf@gitster.g","threadId":"62146","inReplyTo":"Z8WE0SK5QS4aVyYr@pks.im","subject":"Re: Re* [PATCH v2] BreakingChanges: early adopter option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-03-03T16:32:55Z","receivedAt":"2025-03-03T16:32:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Patrick Steinhardt writes:\n\n>> Proposed changes and removals only include items which are \"ready\" to be done.\n>> In other words, this is not supposed to be a wishlist of features that should\n>\n> Thanks, the change look sensible to me.\n\nThanks.\n"}]}