| Message ID | pull.1871.git.1741018310447.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | New |
| 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?
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')