[PATCH v2 1/5] doc: BreakingChanges: transform to a manpage

[kristofferhaugsbakk@fastmail.com]

From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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:

    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 new manpage
gitbreaking-changes(7) in two steps:

1. Transform this document without renaming it (this step)
2. Rename it to gitbreaking-changes(7). But resurrect BreakingChanges in
   order to add a line linking to the new manpage (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’.

Step two is for the next commit.

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

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/BreakingChanges.adoc | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/Documentation/BreakingChanges.adoc b/Documentation/BreakingChanges.adoc
index 73bb939359c..c6b974b6d8c 100644
--- a/Documentation/BreakingChanges.adoc
+++ b/Documentation/BreakingChanges.adoc
@@ -1,4 +1,19 @@
-= 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
@@ -357,3 +372,7 @@ almost no users of any of the commands anymore.
 Cf. <xmqqttjazwwa.fsf@gitster.g>,
 <xmqqleeubork.fsf@gitster.g>,
 <112b6568912a6de6672bf5592c3a718e@manjaro.org>.
+
+GIT
+---
+Part of the linkgit:git[1] suite
-- 
2.55.0.793.gc667de3f2c5