Re: [RFC PATCH 1/4] doc: transform breaking changes doc to a manpage

[Patrick Steinhardt <ps@pks.im>]

On Mon, Sep 28, 2026 at 12:41:25PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> 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.

Yeah, I agree with that sentiment. The one interesting question about it
is of course what we'll do with the document once Git 3.0 is out. Will
we retain it? Will we remove it? Will we empty it and make it focus on
Git 4.0?

I guess once it's a manpage we should definitely retain its contents for
a while longer. The breaking changes will be relevant to users even
after they've already upgraded to Git 3.0. But if so, we should probably
introduce a new section for Git 4.0, at least if we already want to
start thinking about that.

  NB: even if we start thinking about it I think we should probably not
  release it anytime soon. I guess having a major release once per
  decade may be good enough.

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

I feel like a good first step could've been to convert the
BreakingChanges.adoc document in-place to use the new format. Like that,
it would've become way easier to see what's actually changing. The
rename could've then been a 1:1 move.

Patrick