git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Patrick Steinhardt <ps@pks.im>
Date
Oct 22, 2026, 05:54 UTC
Message-ID
<atmk9Q4MRK2JRTlr@pks.im>
In-Reply-To
<xmqqy0bqlqez.fsf@gitster.g>
On Wed, Oct 21, 2026 at 02:00:52PM -0700, Junio C Hamano wrote:
Show 28 quoted lines
> "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
Previous: Junio C Hamano
Message 34 of 34 in “doc: move BreakingChanges to a manpage”
  1. 0/4 doc: move BreakingChanges to a manpagekristofferhaugsbakk@fastmail.com, Sep 28, 2026
  2. 1/4 doc: transform breaking changes doc to a manpagekristofferhaugsbakk@fastmail.com, Sep 28, 2026
  3. Patrick SteinhardtSep 30, 2026
  4. Kristoffer HaugsbakkSep 30, 2026
  5. Patrick SteinhardtSep 30, 2026
  6. 2/4 doc: gitbreaking-changes: replace msg-ids with URLskristofferhaugsbakk@fastmail.com, Sep 28, 2026
  7. Patrick SteinhardtSep 30, 2026
  8. Kristoffer HaugsbakkSep 30, 2026
  9. Junio C HamanoSep 30, 2026
  10. Patrick SteinhardtOct 1, 2026
  11. Kristoffer HaugsbakkOct 3, 2026
  12. Kristoffer HaugsbakkOct 3, 2026
  13. Junio C HamanoOct 4, 2026
  14. Kristoffer HaugsbakkOct 6, 2026
  15. Junio C HamanoOct 6, 2026
  16. 3/4 doc: gitbreaking-changes: add note about living documentkristofferhaugsbakk@fastmail.com, Sep 28, 2026
  17. 4/4 doc: git: mention gitbreaking-changes(7)kristofferhaugsbakk@fastmail.com, Sep 28, 2026
  18. 0/5 doc: move BreakingChanges to a manpagekristofferhaugsbakk@fastmail.com, Oct 8, 2026
  19. 1/5 doc: BreakingChanges: transform to a manpagekristofferhaugsbakk@fastmail.com, Oct 8, 2026
  20. D. Ben KnobleOct 8, 2026
  21. Kristoffer HaugsbakkOct 9, 2026
  22. 2/5 doc: gitbreaking-changes: create from BreakingChangeskristofferhaugsbakk@fastmail.com, Oct 8, 2026
  23. 3/5 doc: gitbreaking-changes: replace msg-ids with URLskristofferhaugsbakk@fastmail.com, Oct 8, 2026
  24. 4/5 doc: gitbreaking-changes: add note about living documentkristofferhaugsbakk@fastmail.com, Oct 8, 2026
  25. 5/5 doc: gitbreaking-changes: move new-items discussion to the endkristofferhaugsbakk@fastmail.com, Oct 8, 2026
  26. Kristoffer HaugsbakkOct 20, 2026
  27. D. Ben KnobleOct 20, 2026
  28. Kristoffer HaugsbakkOct 20, 2026
  29. Junio C HamanoOct 21, 2026
  30. Kristoffer HaugsbakkOct 21, 2026
  31. Junio C HamanoOct 21, 2026
  32. Kristoffer HaugsbakkOct 22, 2026
  33. Junio C HamanoOct 22, 2026
  34. Patrick SteinhardtOct 22, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.