"Phillip Wood via GitGitGadget" <gitgitgadget@xxxxxxxxx> 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?
