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

From: Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com>
Date: Sep 30, 2026, 14:17 UTC
Message-ID: <2e53feae-94fe-4e1b-9665-2a639fe08515@app.fastmail.com>
In-Reply-To: <ar0OicAaDipYx-xU@pks.im>

On Wed, Sep 30, 2026, at 15:28, Patrick Steinhardt wrote:

Show 22 quoted lines

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

I’m glad that this idea makes sense to more than one person. x)

Show 13 quoted lines

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

I know you are wondering out loud here to the fora. But just personally, I imagine that this will happen after Git 3.0:

• A section at the end about Git 3.0 for historical interest as well as
  people on older versions who might be browsing outside of their
  installation (probably git-scm) (and who might be on pre-3.0)
• Git 4.0 discussion before that, however hypothetical or distant the
  release date

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

Like this?

1. Convert to the manpage format without changing the filename
2. Rename the file: pure rename without any other modifications
3. Resurrect `BreakingChanges.adoc` with one line that points to the new
   document

Thanks for reviewing.