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

[Patrick Steinhardt <ps@pks.im>]

On Wed, Sep 30, 2026 at 04:17:44PM +0200, Kristoffer Haugsbakk wrote:
> On Wed, Sep 30, 2026, at 15:28, Patrick Steinhardt wrote:
> > On Mon, Sep 28, 2026 at 12:41:25PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> >> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
> > [...] 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

Yeah, that's also mostly what I arrived at, too.

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

I guess (2) and (3) can easily be combined. I'd hope that Git still
detects this as a 1:1 rename.

Patrick