doc: move BreakingChanges to a manpage
Get series with b4
b4 am [email protected]Versions newest first · linked by author and title
- v2 Latest5 patches 11 repliesIn review
- v1 RFC4 patches 12 repliesSuperseded
Patches in v2 No applies recorded yet
| # | Subject and files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/5 | doc: BreakingChanges: transform to a manpageDocumentation/ | +20 | 2 replies | |
| 2/5 | doc: gitbreaking-changes: create from BreakingChangesDocumentation/ Documentation/ Documentation/ +2 more | +382 | 0 replies | |
| 3/5 | doc: gitbreaking-changes: replace msg-ids with URLsDocumentation/ | +16 | 0 replies | |
| 4/5 | doc: gitbreaking-changes: add note about living documentDocumentation/ | +10 | 0 replies | |
| 5/5 | doc: gitbreaking-changes: move new-items discussion to the endDocumentation/ | +16 | 0 replies |
Reviews trailers per patch
No Reviewed-by, Acked-by or Tested-by trailers for v2 yet.
Cover letter [PATCH v2 0/5] doc: move BreakingChanges to a manpage
From: Kristoffer Haugsbakk <[email protected]>
Topic name: kh/doc-gitbreaking-changes7
Topic summary: Move BreakingChanges document to a manpage for easier visibility.
Notes to the maintainer: conflicts with topics ps/ref-storage-format (in master) and bc/restrict-hex-to-lowercase (in seen). Respectively, they add these things to BreakingChanges.adoc:
(1)
+
Users that get immediate benefit from the "reftable" backend could continue to
-opt-in to the "reftable" format manually by setting the "init.defaultRefFormat" +opt-in to the "reftable" format manually by setting the "init.defaultRefStorageFormat"
(2)
matches the default branch name used in new repositories by many of the big Git forges.
+* Git will accept hex object IDs only in lowercase. The fact that Git has
+ historically allowed uppercase characters in hex object IDs has been the + source of a variety of bugs and security problems in software using Git. We + don't expect most users to notice any change.
(But (2) uses tabs for the three last lines)
So they would need to be moved from BreakingChanges.adoc to gitbreaking-changes.adoc.
***
Users are the ones who are impacted by breaking changes. Certainly much more than Git developers who are already plugged in to the development channels that discuss the trajectory of the project. Advertizing the planned breaking changes to all users will help the whole Git community prepare.
§ Changes in v2
Drop RFC status since Patrick seems to think that this is an okay change.[1]
Patch “mention gitbreaking-changes(7)” is dropped. This is because Julia’s parallel topic je/doc-promote-git-help removes guide-mentions on the git(1) doc.[2]
Series v1 patch “transform breaking changes doc to a manpage” has been split into two in order to make tracing the moved lines easier.[1] I did not go all the way and made another commit for a pure filemove. I think --color-moved should be enough here. But I can of course make another commit.
Note that this split isn’t that obvious from the range diff. It might have been etter if it compared the previous round with the first commit, but futzing with --creation-factor didn’t help me here.
Patch “replace msg-ids with URLs”: fixed unintended space changes. Another linking scheme was discussed but it lead to no changes.[4] But! I found out that one URL does not render properly with asciidoc(1). So I made a compromise for now. Maybe that sinks the URL aspirations here.
Patch “move new-items discussion to the end” is new and based on what I hope is my correct interpretation of Patrick’s suggestion.[3]
† 1: <[email protected]>
† 2: <[email protected]> † 3: <[email protected]>
† 4: <[email protected]>
§ Link to v1
https://lore.kernel.org/git/[email protected]/
[1/5] doc: BreakingChanges: transform to a manpage
[2/5] doc: gitbreaking-changes: create from BreakingChanges [3/5] doc: gitbreaking-changes: replace msg-ids with URLs [4/5] doc: gitbreaking-changes: add note about living document [5/5] doc: gitbreaking-changes: move new-items discussion to the end
Documentation/BreakingChanges.adoc | 360 +---------------------- Documentation/Makefile | 1 + Documentation/gitbreaking-changes.adoc | 389 +++++++++++++++++++++++++ Documentation/meson.build | 1 + command-list.txt | 1 + 5 files changed, 393 insertions(+), 359 deletions(-) create mode 100644 Documentation/gitbreaking-changes.adoc
Interdiff against v1:
Documentation/git.adoc +1 -4
@@ -26,9 +26,7 @@ See linkgit:gittutorial[7] to get started, then see linkgit:giteveryday[7] for a useful minimum set of commands. The link:user-manual.html[Git User's Manual] has a more in-depth introduction. See linkgit:gitdatamodel[7] if you want to -learn about the data model and important terminology. See -linkgit:gitbreaking-changes[7] for a discussion of breaking changes -planned for Git 3.0. +learn about the data model and important terminology. After you mastered the basic concepts, you can come back to this page to learn what commands Git offers. You can learn more about
@@ -1206,7 +1204,6 @@ linkgit:gittutorial[7], linkgit:gittutorial-2[7], linkgit:giteveryday[7], linkgit:gitcvs-migration[7], linkgit:gitglossary[7], linkgit:gitdatamodel[7], linkgit:gitcore-tutorial[7], linkgit:gitcli[7], -linkgit:gitbreaking-changes[7], link:user-manual.html[The Git User's Manual], linkgit:gitworkflows[7]
Documentation/gitbreaking-changes.adoc +20 -18
@@ -54,20 +54,6 @@ breaking releases. Furthermore, this document also tracks what will _not_ be deprecated. This is done such that the outcome of discussions document both when the discussion favors deprecation, but also when it rejects a deprecation. -Items should have a clear summary of the reasons why we do or do not want to -make the described change that can be easily understood without having to read -the mailing list discussions. If there are alternatives to the changed feature, -those alternatives should be pointed out to our users. - -All items should be accompanied by links to relevant mailing list threads -where the deprecation was discussed. These links use this format: - - https://lore.kernel.org/git/$message_id/ - -I.e. they link to the `Message-ID` of the email on the mailing -list. These references are there to make it easier for you to find how -the project reached consensus on the described item back then. - This is a living document as the environment surrounding the project changes over time. If circumstances change, an earlier decision to deprecate or change something may need to be revisited from time to time. So do not take items on
@@ -140,7 +126,7 @@ There is no plan to deprecate the "sha1" object format at this point in time. + Cf. https://lore.kernel.org/git/[email protected], https://lore.kernel.org/git/[email protected], -https://lore.kernel.org/git/CA%2BEOSBncr%3D4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE%[email protected]/. +https://lore.kernel.org/git/CACBZZX65Kbp8N9X9UtBfJca7U1T0m-VtKZeKM5q9mhyCR7dwGg@mail.gmail.com. * The default storage format for references in newly created repositories will be changed from "files" to "reftable". The "reftable" format provides
@@ -341,7 +327,7 @@ The command will be removed. * Support for `core.commentString=auto` has been deprecated and will be removed in Git 3.0. + -cf. https://lore.kernel.org/git/[email protected] +cf. https://lore.kernel.org/git/[email protected] * Support for `core.preferSymlinkRefs=true` has been deprecated and will be removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
@@ -379,8 +365,24 @@ This decision may get revisited in case we ever figure out that there are almost no users of any of the commands anymore. + Cf. https://lore.kernel.org/git/[email protected], -https://lore.kernel.org/git/[email protected], -https://lore.kernel.org/git/[email protected]. + https://lore.kernel.org/git/[email protected], + https://lore.kernel.org/git/[email protected]. + +== Adding new items + +Items should have a clear summary of the reasons why we do or do not want to +make the described change that can be easily understood without having to read +the mailing list discussions. If there are alternatives to the changed feature, +those alternatives should be pointed out to our users. + +All items should be accompanied by links to relevant mailing list threads +where the deprecation was discussed. These links use this format: + + https://lore.kernel.org/git/$message_id/ + +I.e. they link to the `Message-ID` of the email on the mailing +list. These references are there to make it easier for you to find how +the project reached consensus on the described item back then. GIT ---
Range-diff against v1:
-: ----------- > 1: 2b5d0b23a5a doc: BreakingChanges: transform to a manpage 1: 4f98172c30d ! 2: 476d8849135 doc: transform breaking changes doc to a manpage
@@ Metadata
Author: Kristoffer Haugsbakk <[email protected]>
## Commit message ##
- doc: transform breaking changes doc to a manpage
+ doc: gitbreaking-changes: create from BreakingChanges
- 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:
+ We can rename to gitbreaking-changes(7) now that we have changed to
+ the required format in the preceding commit.
- 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.
-
- 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’.
-
- † 1: https://git-scm.com/docs/BreakingChanges.html
- † 2: Which I first mentioned in 098230f7 (you-still-use-that??: help the
- user help themselves, 2025-09-17), footnote #1.
+ But we also need to keep BreakingChanges.adoc in order to point to
+ the new document. That way old links and whatnot are still serviceable.
## Documentation/BreakingChanges.adoc ##
@@
--= Upcoming breaking changes
+-gitbreaking-changes(7)
+-======================
+-
+-NAME
+-----
+-gitbreaking-changes - Breaking changes for upcoming Git 3.0
+-
+-SYNOPSIS
+---------
+-*
+-
+-DESCRIPTION
+------------
+-*
+-
+-== Introduction: Upcoming breaking changes
-
-The Git project aims to ensure backwards compatibility to the best extent -possible. Minor releases will not break backwards compatibility unless there is
@@ Documentation/BreakingChanges.adoc
-Cf. <[email protected]>,
-<[email protected]>, -<[email protected]>.
+-
+-GIT
+----
+-Part of the linkgit:git[1] suite
+This document as been moved to linkgit:gitbreaking-changes[7].
## Documentation/Makefile ##
@@ Documentation/meson.build: manpages = {
'gitcli.adoc' : 7,
'gitcore-tutorial.adoc' : 7,
'gitcredentials.adoc' : 7,
+
+ ## command-list.txt ##
+@@ command-list.txt: git-whatchanged ancillaryinterrogators complete
+ git-worktree mainporcelain
+ git-write-tree plumbingmanipulators
+ gitattributes userinterfaces
++gitbreaking-changes guide
+ gitcli userinterfaces
+ gitcore-tutorial guide
+ gitcredentials guide
2: a6626aafac8 ! 3: c8983aced71 doc: gitbreaking-changes: replace msg-ids with URLs
@@ Commit message
† 1: 57ec9254 (docs: introduce document to announce breaking changes, 2024-06-14)
- Note that we have to URL encode two msg-ids:
+ Note that we have to URL encode this msg-id:
CAKvOHKAFXQwt4D8yUCCkf_TQL79mYaJ=KAKhtpDNTvHJFuX1NA@mail.gmail.com
+
+ Lore can handle it just fine, but asciidoctor(1) cannot.
+
+ Worse yet, this msg-id can be handled by asciidoctor(1) but not by
+ asciidoc:
+
CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com
- Lore can handle them just fine, but asciidoctor(1) cannot.
+ URL encoding does not help. So compromise by linking to the only
+ second-level reply:
+
+ CACBZZX65Kbp8N9X9UtBfJca7U1T0m-VtKZeKM5q9mhyCR7dwGg@mail.gmail.com
+
+ Which properly quotes the first message. So no loss of fidelity in
+ my opinion.
@@ Documentation/gitbreaking-changes.adoc: applications and forges.
-<CA+EOSBncr=4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE+DiUQ@mail.gmail.com>.
+Cf. https://lore.kernel.org/git/[email protected],
+https://lore.kernel.org/git/[email protected],
-+https://lore.kernel.org/git/CA%2BEOSBncr%3D4a4d8n9xS4FNehyebpmX8JiUwCsXD47EQDE%[email protected]/. ++https://lore.kernel.org/git/CACBZZX65Kbp8N9X9UtBfJca7U1T0m-VtKZeKM5q9mhyCR7dwGg@mail.gmail.com.
* The default storage format for references in newly created repositories will be changed from "files" to "reftable". The "reftable" format provides
@@ Documentation/gitbreaking-changes.adoc: The command will be removed.
be removed in Git 3.0.
+
-cf. <[email protected]>
-+cf. https://lore.kernel.org/git/[email protected]
++cf. https://lore.kernel.org/git/[email protected]
* Support for core.preferSymlinkRefs=true has been deprecated and will be removed in Git 3.0. Writing symbolic refs as symbolic links will be phased
@@ Documentation/gitbreaking-changes.adoc: those features with newer alternatives.
-<[email protected]>, -<[email protected]>.
+Cf. https://lore.kernel.org/git/[email protected],
-+https://lore.kernel.org/git/[email protected], -+https://lore.kernel.org/git/[email protected].
++ https://lore.kernel.org/git/[email protected],
++ https://lore.kernel.org/git/[email protected].
GIT
---
3: 75397436eb9 = 4: 46f08bb65d9 doc: gitbreaking-changes: add note about living document 4: 9d14f13664f < -: ----------- doc: git: mention gitbreaking-changes(7) -: ----------- > 5: 85fe7ebe89e doc: gitbreaking-changes: move new-items discussion to the end
base-commit: 0f8e75abebff0877cae681a3d5ff31ac47f54220
Signature · 1 line
2.55.0.793.gc667de3f2c5