From: Junio C Hamano Date: Thu, 22 Oct 2026 16:38:04 GMT Subject: Re: [PATCH v2 0/5] doc: move BreakingChanges to a manpage Message-ID: In-Reply-To: "Kristoffer Haugsbakk" writes: > 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. OK. I was merely expressing my worry that it might be awkward post the transition, but if the manpages (where? in section 7 perhaps) is the easiest to arrange and will not be awkward to have after the transition, then let's do that. Thanks.