From: Kristoffer Haugsbakk Date: Thu, 22 Oct 2026 05:18:27 GMT Subject: Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage Message-ID: In-Reply-To: On Wed, Oct 21, 2026, at 23:00, Junio C Hamano wrote: > "Kristoffer Haugsbakk" writes: > >> On Wed, Oct 21, 2026, at 18:50, Junio C Hamano wrote: >>> "D. Ben Knoble" writes: >>>> [snip] >>> >>> 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: >> >> 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? I’ve mostly just outlined how either approach can be handled. Personally I’m fine either way. As far as being a living document is concerned, discussions of old versions could be promptly deleted. People who are on older versions will have the relevant discussion in their installation. Beyond that people can use the power of version control spelunking. As an alternative you could keep just the previous breaking change discussion like mentioned in . Like, when you’re approaching Git 5.0 there will just be Git 5.0 and Git 4.0 discussions left in the doc.