| Message ID | pull.1871.git.1741018310447.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | docs: fix repository-layout when building with breaking changes | expand |
"Phillip Wood via GitGitGadget" <gitgitgadget@gmail.com> writes: > I copied the name from the test prerequisite as I didn't want to have > different names for condition used in the tests and documentation. I do > have some reservations about the naming though as it means we end up > having to use ifdef::!without-breaking-changes[] or test_expect_success > !WITHOUT_BREAKING_CHANGES to document and test breaking changes which is > a double negative. It was exactly the first thing that came to my mind when I saw the change to the Makefile in the patch. Unless our breaking changes are all removals, which is not likely to be the case in the longer term, "without-breaking-changes" would be an invitation for confusing double negatives. > +ifdef::without-breaking-changes[] > branches:: > A deprecated way to store shorthands to be used > to specify a URL to 'git fetch', 'git pull' and 'git push'. > @@ -164,6 +165,7 @@ branches:: > "$GIT_COMMON_DIR/branches" will be used instead. > + > Git will stop reading remotes from this directory in Git 3.0. > +endif::without-breaking-changes[] > > hooks:: > Hooks are customization scripts used by various Git > @@ -231,6 +233,7 @@ info/sparse-checkout:: > This file stores sparse checkout patterns. > See also: linkgit:git-read-tree[1]. > > +ifdef::without-breaking-changes[] > remotes:: > Stores shorthands for URL and default refnames for use > when interacting with remote repositories via 'git fetch', > @@ -241,6 +244,7 @@ remotes:: > "$GIT_COMMON_DIR/remotes" will be used instead. > + > Git will stop reading remotes from this directory in Git 3.0. > +endif::without-breaking-changes[] > > logs:: > Records of changes made to refs are stored in this directory. The above parts of the documentation getting commented out all look sensible to exclude in a build that omits these older mechanisms. But can we do it with !with-breaking-changes instead?
On Mon, Mar 03, 2025 at 10:18:05AM -0800, Junio C Hamano wrote: > "Phillip Wood via GitGitGadget" <gitgitgadget@gmail.com> writes: > > > I copied the name from the test prerequisite as I didn't want to have > > different names for condition used in the tests and documentation. I do > > have some reservations about the naming though as it means we end up > > having to use ifdef::!without-breaking-changes[] or test_expect_success > > !WITHOUT_BREAKING_CHANGES to document and test breaking changes which is > > a double negative. > > It was exactly the first thing that came to my mind when I saw the > change to the Makefile in the patch. Unless our breaking changes > are all removals, which is not likely to be the case in the longer > term, "without-breaking-changes" would be an invitation for > confusing double negatives. I remember not quite being happy with the double-negation myself. I don't mind renaming the prerequisite we have in our test suite for consistency, as well, if you want to do that. Patrick
Hi Patrick On 04/03/2025 06:35, Patrick Steinhardt wrote: > On Mon, Mar 03, 2025 at 10:18:05AM -0800, Junio C Hamano wrote: >> "Phillip Wood via GitGitGadget" <gitgitgadget@gmail.com> writes: >> >>> I copied the name from the test prerequisite as I didn't want to have >>> different names for condition used in the tests and documentation. I do >>> have some reservations about the naming though as it means we end up >>> having to use ifdef::!without-breaking-changes[] or test_expect_success >>> !WITHOUT_BREAKING_CHANGES to document and test breaking changes which is >>> a double negative. >> >> It was exactly the first thing that came to my mind when I saw the >> change to the Makefile in the patch. Unless our breaking changes >> are all removals, which is not likely to be the case in the longer >> term, "without-breaking-changes" would be an invitation for >> confusing double negatives. > > I remember not quite being happy with the double-negation myself. I > don't mind renaming the prerequisite we have in our test suite for > consistency, as well, if you want to do that. Yes, I can do that when I re-roll the patches at https://lore.kernel.org/git/pull.1863.git.1740149837.gitgitgadget@gmail.com/ to use WITH_BREAKING_CHANGES Best Wishes Phillip > Patrick >
Phillip Wood <phillip.wood123@gmail.com> writes: >> I remember not quite being happy with the double-negation myself. I >> don't mind renaming the prerequisite we have in our test suite for >> consistency, as well, if you want to do that. > > Yes, I can do that when I re-roll the patches at > https://lore.kernel.org/git/pull.1863.git.1740149837.gitgitgadget@gmail.com/ > to use WITH_BREAKING_CHANGES Thanks, both.
diff --git a/Documentation/Makefile b/Documentation/Makefile index a734c6d6243..53a05eb8030 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -221,6 +221,10 @@ asciidoc.conf: asciidoc.conf.in FORCE $(QUIET_GEN)$(call version_gen,"$(shell pwd)/..",$<,$@) endif +ifndef WITH_BREAKING_CHANGES +ASCIIDOC_EXTRA += -awithout-breaking-changes +endif + ASCIIDOC_DEPS += docinfo.html SHELL_PATH ?= $(SHELL) diff --git a/Documentation/gitrepository-layout.adoc b/Documentation/gitrepository-layout.adoc index 6348ef1dcdf..62ef1c98c26 100644 --- a/Documentation/gitrepository-layout.adoc +++ b/Documentation/gitrepository-layout.adoc @@ -152,6 +152,7 @@ config.worktree:: working directory in multiple working directory setup (see linkgit:git-worktree[1]). +ifdef::without-breaking-changes[] branches:: A deprecated way to store shorthands to be used to specify a URL to 'git fetch', 'git pull' and 'git push'. @@ -164,6 +165,7 @@ branches:: "$GIT_COMMON_DIR/branches" will be used instead. + Git will stop reading remotes from this directory in Git 3.0. +endif::without-breaking-changes[] hooks:: Hooks are customization scripts used by various Git @@ -231,6 +233,7 @@ info/sparse-checkout:: This file stores sparse checkout patterns. See also: linkgit:git-read-tree[1]. +ifdef::without-breaking-changes[] remotes:: Stores shorthands for URL and default refnames for use when interacting with remote repositories via 'git fetch', @@ -241,6 +244,7 @@ remotes:: "$GIT_COMMON_DIR/remotes" will be used instead. + Git will stop reading remotes from this directory in Git 3.0. +endif::without-breaking-changes[] logs:: Records of changes made to refs are stored in this directory. diff --git a/Documentation/meson.build b/Documentation/meson.build index ead8e482131..4e4fca283c1 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -283,6 +283,10 @@ elif docs_backend == 'asciidoctor' ] endif +if not get_option('breaking_changes') + asciidoc_common_options += ['--attribute', 'without-breaking-changes'] +endif + git = find_program('git', required: false) xmlto = find_program('xmlto')