Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage

[Patrick Steinhardt <ps@pks.im>]

On Wed, Oct 21, 2026 at 02:00:52PM -0700, Junio C Hamano wrote:
> "Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
> 
> > On Wed, Oct 21, 2026, at 18:50, Junio C Hamano wrote:
> >> "D. Ben Knoble" <ben.knoble@gmail.com> writes:
> >>
> >>>> Is there any interest in continuing this series?
> >>>
> >>> For myself, I favor making more of Git's documentation accessible to folks.
> >>
> >> I do not know about "manual pages", but making this available from
> >> "git help" would be good.  It raises a huge question about what to
> >> do when Git 3.0 comes, though.  Are we going to change every section
> >> and rewrite them to say "we used to do this differently before 3.0"?
> >
> > See me and Patrick’s subthread: <ar0OicAaDipYx-xU@pks.im>
> >
> > You could transform it into a section at the end for “what happened in 3.0” then introduce it with
> >
> >     These things changed in 3.0. They are written in the future tense
> >     [?] is reading about what will happen coming from version 2.98 to
> >     3.0.
> >
> > Then you wouldn’t need to change any of the rest of the text.
> 
> The rewriting effort is not a major concern.  Rather, the question
> is whether keeping such a historical document is worth it.  Do you
> still care about what the major issues were when we transitioned
> from Git 1.x to 2.0, for example?

Probably not two decades later, but at least for the next couple of
years I'd assume. It's likely that upgrades jump multiple versions at a
time, for example because the user upgraded from one LTS release to the
next one. So they may or may not land on Git 3.0 directly, but it's more
likely to assume that they'l land on 3.x where x != 0. And these users
would still want to learn about what has changed in the major release.

So I'd say that it makes sense to keep it until at least all of our
supported distributions have upgraded to Git 3.0 already.

Patrick