[v2] docs: remove pre-v1.6.0 "repack --delta-base-offset" docs

Commit Message

Ævar Arnfjörð Bjarmason July 19, 2022, 12:09 a.m. UTC

Remove documentation about --delta-base-offset that's only pertinent
to those running versions of git older than v1.4.4 and v1.6.0. Both of
those versions are too ancient to care about.

For the purposes of evaluating this change it only matters that v1.6.0
is too old at this point for anyone to care about, since the change in
default behavior discussed in the removed documentation impacted
pre-v1.4.4 versions of git.

Details:

A. As the documentation notes the "--delta-base-offset" switch
   introduced in 1.4.4[1] became the default in 1.6.0[2]. The "by
   default" part of the removed documentation discusses a change in what
   had been the status quo in v1.4.4..v1.6.0^.

B. When exactly "--delta-base-offset" was introduced and when it
   became the default (as noted in "A" above) is only of academic
   interest once we decide that anything older than 1.6.0 isn't worth
   caring about.

   The documentation being removed here was added in [3] and [4],
   which were first released with v1.4.4 and v1.7.0, respectively. At
   the time it was of interest to someone running v1.6.0 or later that
   they'd be creating packs incompatible with older git versions.

   But at some point the last user of v1.4.4 in the wild would have
   went away, presumably followed some time afterwards by the last
   v1.4.4..v1.6.0^ user.

   If we were turning back the clock we might have removed the
   "incompatible with" part of this documentation once v1.4.4 became
   irrelevant, but as v1.6.0 was still relevant kept the "by default"
   part.

   But as neither are relevant at this point let's remove this entire
   paragraph[5].

1. be6b19145f6 (make git-pack-objects able to create deltas with
   offset to base, 2006-09-21)
2. 22c79eab295 (repack.usedeltabaseoffset config option now defaults
   to "true", 2008-06-25)
3. b6945f570ac (git-repack: repo.usedeltabaseoffset, 2006-10-13)
4. 9f17688d93c (update git-repack documentation wrt
   repack.UseDeltaBaseOffset, 2010-02-04).
5. In <xmqqsfn21fmt.fsf@gitster.g> [6] Junio suggests that anything
   older than v2.0.0 or v2.16.0 isn't relevant at this point

   I think that's defensible, but as e.g. "gcc110" on the GCC Farm has
   a /usr/bin/git version v1.8.3.1 (which was released in mid-2013)
   that would be a different argument.

   As that case shows there are still OS's with 2013-era software in
   common use (particularly RHEL and its derivatives).

   But I don't think anyone knows about or can plausibly contrive a
   scenario where someone still is still v1.6.0 or older, and might
   therefore benefit from these docs.

   We might want to follow-up with removal of documentation that only
   benefits users of those ancient version, and tell them that they
   should consult their OS-installed documentation, newer git isn't
   going to carry those backwards compatibility notes forward.

   But as long as there are still systems in active use with those
   versions let's leave that to a future follow-up, either because
   it's far enough in the future that those versions are truly dead,
   or because we'd like to drop documentation in that category.
6. https://lore.kernel.org/git/xmqqsfn21fmt.fsf@gitster.g/

Signed-off-by: Ævar Arnfjörð Bjarmason <[e-mail]>

Changes in v2:

 * Updated commit message per
   https://lore.kernel.org/git/[e-mail]/

---
Range-diff against v1:
1:  363f84a3fa7 ! 1:  98b6de56019 git-repack doc: remove discussion of ancient caveat
    @@ Metadata
     Author: Ævar Arnfjörð Bjarmason <[e-mail]>
     
      ## Commit message ##
    -    git-repack doc: remove discussion of ancient caveat
    +    docs: remove pre-v1.6.0 "repack --delta-base-offset" docs
     
    -    The backwards compatibility caveat discussed her hasn't been a concern
    -    for anyone after Git v1.6.0. Let's simply remove it, I daresay
    -    nobody's concerned these days with having git clients running older
    -    than 2008-era git.
    +    Remove documentation about --delta-base-offset that's only pertinent
    +    to those running versions of git older than v1.4.4 and v1.6.0. Both of
    +    those versions are too ancient to care about.
     
    -    See b6945f570ac (git-repack: repo.usedeltabaseoffset, 2006-10-13) and
    -    9f17688d93c (update git-repack documentation wrt
    -    repack.UseDeltaBaseOffset, 2010-02-04) for the commits that previously
    -    introduced and adjusted this documentation.
    +    For the purposes of evaluating this change it only matters that v1.6.0
    +    is too old at this point for anyone to care about, since the change in
    +    default behavior discussed in the removed documentation impacted
    +    pre-v1.4.4 versions of git.
    +
    +    Details:
    +
    +    A. As the documentation notes the "--delta-base-offset" switch
    +       introduced in 1.4.4[1] became the default in 1.6.0[2]. The "by
    +       default" part of the removed documentation discusses a change in what
    +       had been the status quo in v1.4.4..v1.6.0^.
    +
    +    B. When exactly "--delta-base-offset" was introduced and when it
    +       became the default (as noted in "A" above) is only of academic
    +       interest once we decide that anything older than 1.6.0 isn't worth
    +       caring about.
    +
    +       The documentation being removed here was added in [3] and [4],
    +       which were first released with v1.4.4 and v1.7.0, respectively. At
    +       the time it was of interest to someone running v1.6.0 or later that
    +       they'd be creating packs incompatible with older git versions.
    +
    +       But at some point the last user of v1.4.4 in the wild would have
    +       went away, presumably followed some time afterwards by the last
    +       v1.4.4..v1.6.0^ user.
    +
    +       If we were turning back the clock we might have removed the
    +       "incompatible with" part of this documentation once v1.4.4 became
    +       irrelevant, but as v1.6.0 was still relevant kept the "by default"
    +       part.
    +
    +       But as neither are relevant at this point let's remove this entire
    +       paragraph[5].
    +
    +    1. be6b19145f6 (make git-pack-objects able to create deltas with
    +       offset to base, 2006-09-21)
    +    2. 22c79eab295 (repack.usedeltabaseoffset config option now defaults
    +       to "true", 2008-06-25)
    +    3. b6945f570ac (git-repack: repo.usedeltabaseoffset, 2006-10-13)
    +    4. 9f17688d93c (update git-repack documentation wrt
    +       repack.UseDeltaBaseOffset, 2010-02-04).
    +    5. In <xmqqsfn21fmt.fsf@gitster.g> [6] Junio suggests that anything
    +       older than v2.0.0 or v2.16.0 isn't relevant at this point
    +
    +       I think that's defensible, but as e.g. "gcc110" on the GCC Farm has
    +       a /usr/bin/git version v1.8.3.1 (which was released in mid-2013)
    +       that would be a different argument.
    +
    +       As that case shows there are still OS's with 2013-era software in
    +       common use (particularly RHEL and its derivatives).
    +
    +       But I don't think anyone knows about or can plausibly contrive a
    +       scenario where someone still is still v1.6.0 or older, and might
    +       therefore benefit from these docs.
    +
    +       We might want to follow-up with removal of documentation that only
    +       benefits users of those ancient version, and tell them that they
    +       should consult their OS-installed documentation, newer git isn't
    +       going to carry those backwards compatibility notes forward.
    +
    +       But as long as there are still systems in active use with those
    +       versions let's leave that to a future follow-up, either because
    +       it's far enough in the future that those versions are truly dead,
    +       or because we'd like to drop documentation in that category.
    +    6. https://lore.kernel.org/git/xmqqsfn21fmt.fsf@gitster.g/
     
         Signed-off-by: Ævar Arnfjörð Bjarmason <[e-mail]>
     

 Documentation/git-repack.txt | 10 ----------
 1 file changed, 10 deletions(-)

Patch

diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
index 0bf13893d81..fe1eac37090 100644
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.txt
@@ -218,16 +218,6 @@  CONFIGURATION
 Various configuration variables affect packing, see
 linkgit:git-config[1] (search for "pack" and "delta").
 
-By default, the command passes `--delta-base-offset` option to
-'git pack-objects'; this typically results in slightly smaller packs,
-but the generated packs are incompatible with versions of Git older than
-version 1.4.4. If you need to share your repository with such ancient Git
-versions, either directly or via the dumb http protocol, then you
-need to set the configuration variable `repack.UseDeltaBaseOffset` to
-"false" and repack. Access from old Git versions over the native protocol
-is unaffected by this option as the conversion is performed on the fly
-as needed in that case.
-
 Delta compression is not used on objects larger than the
 `core.bigFileThreshold` configuration variable and on files with the
 attribute `delta` set to false.