[PATCH v2 0/5] doc: move BreakingChanges to a manpage

[kristofferhaugsbakk@fastmail.com]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

Topic name: kh/doc-gitbreaking-changes7

Topic summary: Move BreakingChanges document to a manpage for easier
visibility.

Notes to the maintainer: conflicts with topics ps/ref-storage-format (in
`master`) and bc/restrict-hex-to-lowercase (in `seen`). Respectively, they
add these things to `BreakingChanges.adoc`:

(1)

     +
     Users that get immediate benefit from the "reftable" backend could continue to
    -opt-in to the "reftable" format manually by setting the "init.defaultRefFormat"
    +opt-in to the "reftable" format manually by setting the "init.defaultRefStorageFormat"

(2)

      matches the default branch name used in new repositories by many of the
      big Git forges.

   +* Git will accept hex object IDs only in lowercase. The fact that Git has
   +        historically allowed uppercase characters in hex object IDs has been the
   +        source of a variety of bugs and security problems in software using Git. We
   +        don't expect most users to notice any change.

(But (2) uses tabs for the three last lines)

So they would need to be moved from `BreakingChanges.adoc` to
`gitbreaking-changes.adoc`.

***

Users are the ones who are impacted by breaking changes. Certainly much
more than Git developers who are already plugged in to the development
channels that discuss the trajectory of the project. Advertizing the
planned breaking changes to all users will help the whole Git community
prepare.

§ Changes in v2

Drop RFC status since Patrick seems to think that this is an okay
change.[1]

Patch “mention gitbreaking-changes(7)” is dropped. This is because Julia’s
parallel topic je/doc-promote-git-help removes guide-mentions on the git(1)
doc.[2]

Series v1 patch “transform breaking changes doc to a manpage” has been
split into two in order to make tracing the moved lines easier.[1] I did
not go all the way and made another commit for a pure filemove. I think
`--color-moved` should be enough here. But I can of course make another
commit.

Note that this split isn’t that obvious from the range diff. It might have
been etter if it compared the previous round with the first commit, but
futzing with `--creation-factor` didn’t help me here.

Patch “replace msg-ids with URLs”: fixed unintended space changes. Another
linking scheme was discussed but it lead to no changes.[4] But! I found out
that one URL does not render properly with asciidoc(1). So I made a
compromise for now. Maybe that sinks the URL aspirations here.

Patch “move new-items discussion to the end” is new and based on what I
hope is my correct interpretation of Patrick’s suggestion.[3]

† 1: <ar0OicAaDipYx-xU@pks.im>
† 2: <ea29fe74-7f76-440c-9597-fdbc173be90f@app.fastmail.com>
† 3: <ar0OltAkeTiCx81c@pks.im>
† 4: <xmqqeceaa5h9.fsf@gitster.g>

§ Link to v1

https://lore.kernel.org/git/CV_gitbrchanges7_please.d1c@m5gid.xyz/

[1/5] doc: BreakingChanges: transform to a manpage
[2/5] doc: gitbreaking-changes: create from BreakingChanges
[3/5] doc: gitbreaking-changes: replace msg-ids with URLs
[4/5] doc: gitbreaking-changes: add note about living document
[5/5] doc: gitbreaking-changes: move new-items discussion to the end

 Documentation/BreakingChanges.adoc     | 360 +----------------------
 Documentation/Makefile                 |   1 +
 Documentation/gitbreaking-changes.adoc | 389 +++++++++++++++++++++++++
 Documentation/meson.build              |   1 +
 command-list.txt                       |   1 +
 5 files changed, 393 insertions(+), 359 deletions(-)
 create mode 100644 Documentation/gitbreaking-changes.adoc

Interdiff against v1:
diff --git a/Documentation/git.adoc b/Documentation/git.adoc
index 6a4ef2dff5c..6f0075f9188 100644
--- a/Documentation/git.adoc
+++ b/Documentation/git.adoc
@@ -26,9 +26,7 @@ See linkgit:gittutorial[7] to get started, then see
 linkgit:giteveryday[7] for a useful minimum set of
 commands.  The link:user-manual.html[Git User's Manual] has a more
 in-depth introduction.  See linkgit:gitdatamodel[7] if you want to
-learn about the data model and important terminology.  See
-linkgit:gitbreaking-changes[7] for a discussion of breaking changes
-planned for Git 3.0.
+learn about the data model and important terminology.
 
 After you mastered the basic concepts, you can come back to this
 page to learn what commands Git offers.  You can learn more about
@@ -1206,7 +1204,6 @@ linkgit:gittutorial[7], linkgit:gittutorial-2[7],
 linkgit:giteveryday[7], linkgit:gitcvs-migration[7],
 linkgit:gitglossary[7], linkgit:gitdatamodel[7],
 linkgit:gitcore-tutorial[7], linkgit:gitcli[7],
-linkgit:gitbreaking-changes[7],
 link:user-manual.html[The Git User's Manual],
 linkgit:gitworkflows[7]
 
diff --git a/Documentation/gitbreaking-changes.adoc b/Documentation/gitbreaking-changes.adoc
index 410476c7993..e984c2c8ca5 100644
--- a/Documentation/gitbreaking-changes.adoc
+++ b/Documentation/gitbreaking-changes.adoc
@@ -54,20 +54,6 @@ breaking releases. Furthermore, this document also tracks what will _not_ be
 deprecated. This is done such that the outcome of discussions document both
 when the discussion favors deprecation, but also when it rejects a deprecation.
 
-Items should have a clear summary of the reasons why we do or do not want to
-make the described change that can be easily understood without having to read
-the mailing list discussions. If there are alternatives to the changed feature,
-those alternatives should be pointed out to our users.
-
-All items should be accompanied by links to relevant mailing list threads
-where the deprecation was discussed. These links use this format:
-
-  https://lore.kernel.org/git/$message_id/
-
-I.e. they link to the `Message-ID` of the email on the mailing
-list. These references are there to make it easier for you to find how
-the project reached consensus on the described item back then.
-
 This is a living document as the environment surrounding the project changes
 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
@@ -140,7 +126,7 @@ There is no plan to deprecate the "sha1" object format at this point in time.
 +
 Cf. https://lore.kernel.org/git/2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com,
 https://lore.kernel.org/git/20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain,
-https://lore.kernel.org/git/CA%2BEOSBncr%3D4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE%2BDiUQ@mail.gmail.com/.
+https://lore.kernel.org/git/CACBZZX65Kbp8N9X9UtBfJca7U1T0m-VtKZeKM5q9mhyCR7dwGg@mail.gmail.com.
 
 * The default storage format for references in newly created repositories will
   be changed from "files" to "reftable". The "reftable" format provides
@@ -341,7 +327,7 @@ The command will be removed.
 * Support for `core.commentString=auto` has been deprecated and will
   be removed in Git 3.0.
 +
-cf.  https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g
+cf. https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g
 
 * Support for `core.preferSymlinkRefs=true` has been deprecated and will be
   removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
@@ -379,8 +365,24 @@ This decision may get revisited in case we ever figure out that there are
 almost no users of any of the commands anymore.
 +
 Cf. https://lore.kernel.org/git/xmqqttjazwwa.fsf@gitster.g,
-https://lore.kernel.org/git/xmqqleeubork.fsf@gitster.g,
-https://lore.kernel.org/git/112b6568912a6de6672bf5592c3a718e@manjaro.org.
+    https://lore.kernel.org/git/xmqqleeubork.fsf@gitster.g,
+    https://lore.kernel.org/git/112b6568912a6de6672bf5592c3a718e@manjaro.org.
+
+== Adding new items
+
+Items should have a clear summary of the reasons why we do or do not want to
+make the described change that can be easily understood without having to read
+the mailing list discussions. If there are alternatives to the changed feature,
+those alternatives should be pointed out to our users.
+
+All items should be accompanied by links to relevant mailing list threads
+where the deprecation was discussed. These links use this format:
+
+  https://lore.kernel.org/git/$message_id/
+
+I.e. they link to the `Message-ID` of the email on the mailing
+list. These references are there to make it easier for you to find how
+the project reached consensus on the described item back then.
 
 GIT
 ---
Range-diff against v1:
-:  ----------- > 1:  2b5d0b23a5a doc: BreakingChanges: transform to a manpage
1:  4f98172c30d ! 2:  476d8849135 doc: transform breaking changes doc to a manpage
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: transform breaking changes doc to a manpage
    +    doc: gitbreaking-changes: create from BreakingChanges
     
    -    The breaking changes document is not a regular Git documentation page.
    -    That means that you cannot navigate to the doc with git(1), i.e. with:
    +    We can rename to gitbreaking-changes(7) now that we have changed to
    +    the required format in the preceding commit.
     
    -        git help BreakingChanges
    -
    -    You instead have to download the Git project source. Or go to
    -    git-scm.com.[1] Then you get this disclaimer:[2]
    -
    -        This information is specific to the Git project
    -
    -        Please note that this information is only relevant to you if you
    -        plan on contributing to the Git project itself. It is in no shape or
    -        form required reading for regular Git users.
    -
    -    But this document is relevant to *all* Git users. Everyone should have
    -    as easy access to it as the other doc and guide pages.
    -
    -    To that end, let’s move the text to a manpage. But keep the old page,
    -    just linking to the new one. (We wouldn’t want to break any readers.)
    -
    -    Just do the minimal changes for the new format. Also demote the first
    -    section to the second level, i.e. make “Introduction” the same level
    -    as “Procedure’.
    -
    -    † 1: https://git-scm.com/docs/BreakingChanges.html
    -    † 2: Which I first mentioned in 098230f7 (you-still-use-that??: help the
    -         user help themselves, 2025-09-17), footnote #1.
    +    But we also need to keep `BreakingChanges.adoc` in order to point to
    +    the new document. That way old links and whatnot are still serviceable.
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Documentation/BreakingChanges.adoc ##
     @@
    --= Upcoming breaking changes
    +-gitbreaking-changes(7)
    +-======================
    +-
    +-NAME
    +-----
    +-gitbreaking-changes - Breaking changes for upcoming Git 3.0
    +-
    +-SYNOPSIS
    +---------
    +-*
    +-
    +-DESCRIPTION
    +------------
    +-*
    +-
    +-== Introduction: Upcoming breaking changes
     -
     -The Git project aims to ensure backwards compatibility to the best extent
     -possible. Minor releases will not break backwards compatibility unless there is
    @@ Documentation/BreakingChanges.adoc
     -Cf. <xmqqttjazwwa.fsf@gitster.g>,
     -<xmqqleeubork.fsf@gitster.g>,
     -<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
    +-
    +-GIT
    +----
    +-Part of the linkgit:git[1] suite
     +This document as been moved to linkgit:gitbreaking-changes[7].
     
      ## Documentation/Makefile ##
    @@ Documentation/meson.build: manpages = {
        'gitcli.adoc' : 7,
        'gitcore-tutorial.adoc' : 7,
        'gitcredentials.adoc' : 7,
    +
    + ## command-list.txt ##
    +@@ command-list.txt: git-whatchanged                         ancillaryinterrogators          complete
    + git-worktree                            mainporcelain
    + git-write-tree                          plumbingmanipulators
    + gitattributes                           userinterfaces
    ++gitbreaking-changes                     guide
    + gitcli                                  userinterfaces
    + gitcore-tutorial                        guide
    + gitcredentials                          guide
2:  a6626aafac8 ! 3:  c8983aced71 doc: gitbreaking-changes: replace msg-ids with URLs
    @@ Commit message
     
         † 1: 57ec9254 (docs: introduce document to announce breaking changes, 2024-06-14)
     
    -    Note that we have to URL encode two msg-ids:
    +    Note that we have to URL encode this msg-id:
     
              CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com
    +
    +    Lore can handle it just fine, but asciidoctor(1) cannot.
    +
    +    Worse yet, this msg-id can be handled by asciidoctor(1) but not by
    +    asciidoc:
    +
              CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com
     
    -    Lore can handle them just fine, but asciidoctor(1) cannot.
    +    URL encoding does not help. So compromise by linking to the only
    +    second-level reply:
    +
    +        CACBZZX65Kbp8N9X9UtBfJca7U1T0m-VtKZeKM5q9mhyCR7dwGg@mail.gmail.com
    +
    +    Which properly quotes the first message. So no loss of fidelity in
    +    my opinion.
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    @@ Documentation/gitbreaking-changes.adoc: applications and forges.
     -<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
     +Cf. https://lore.kernel.org/git/2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com,
     +https://lore.kernel.org/git/20170223155046.e7nxivfwqqoprsqj@LykOS.localdomain,
    -+https://lore.kernel.org/git/CA%2BEOSBncr%3D4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE%2BDiUQ@mail.gmail.com/.
    ++https://lore.kernel.org/git/CACBZZX65Kbp8N9X9UtBfJca7U1T0m-VtKZeKM5q9mhyCR7dwGg@mail.gmail.com.
      
      * The default storage format for references in newly created repositories will
        be changed from "files" to "reftable". The "reftable" format provides
    @@ Documentation/gitbreaking-changes.adoc: The command will be removed.
        be removed in Git 3.0.
      +
     -cf. <xmqqa59i45wc.fsf@gitster.g>
    -+cf.  https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g
    ++cf. https://lore.kernel.org/git/xmqqa59i45wc.fsf@gitster.g
      
      * Support for `core.preferSymlinkRefs=true` has been deprecated and will be
        removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
    @@ Documentation/gitbreaking-changes.adoc: those features with newer alternatives.
     -<xmqqleeubork.fsf@gitster.g>,
     -<112b6568912a6de6672bf5592c3a718e@manjaro.org>.
     +Cf. https://lore.kernel.org/git/xmqqttjazwwa.fsf@gitster.g,
    -+https://lore.kernel.org/git/xmqqleeubork.fsf@gitster.g,
    -+https://lore.kernel.org/git/112b6568912a6de6672bf5592c3a718e@manjaro.org.
    ++    https://lore.kernel.org/git/xmqqleeubork.fsf@gitster.g,
    ++    https://lore.kernel.org/git/112b6568912a6de6672bf5592c3a718e@manjaro.org.
      
      GIT
      ---
3:  75397436eb9 = 4:  46f08bb65d9 doc: gitbreaking-changes: add note about living document
4:  9d14f13664f < -:  ----------- doc: git: mention gitbreaking-changes(7)
-:  ----------- > 5:  85fe7ebe89e doc: gitbreaking-changes: move new-items discussion to the end

base-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220
-- 
2.55.0.793.gc667de3f2c5