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

From: Patrick Steinhardt <ps@pks.im>
Date: Sep 30, 2026, 13:28 UTC
Message-ID: <ar0OicAaDipYx-xU@pks.im>
In-Reply-To: <gitbrchanges7_please.d1d@m5gid.xyz>

On Mon, Sep 28, 2026 at 12:41:25PM +0200, kristofferhaugsbakk@fastmail.com wrote:

Show 18 quoted lines

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

Show 6 quoted lines

> 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