From: Kristoffer Haugsbakk Date: Wed, 30 Sep 2026 14:17:44 GMT Subject: Re: [RFC PATCH 1/4] doc: transform breaking changes doc to a manpage Message-ID: <2e53feae-94fe-4e1b-9665-2a639fe08515@app.fastmail.com> In-Reply-To: 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 >> >> 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) > [...] 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 > >> 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.