[PATCH v7 3/4] BreakingChanges: document removal of grafting

From: Patrick Steinhardt <ps@pks.im>
Date: Jun 14, 2024, 06:42 UTC
Message-ID: <deee0bbf667892141b2c79567d946521517fe943.1718345026.git.ps@pks.im>
In-Reply-To: <cover.1718345026.git.ps@pks.im>

The grafting mechanism for objects has been deprecated in e650d0643b (docs: mark info/grafts as outdated, 2014-03-05), which is more than a decade ago. The mechanism can lead to hard-to-debug issues and has a superior replacement with replace refs.

Follow through with the deprecation and mark grafts for removal in Git 3.0.

Signed-off-by: Patrick Steinhardt <ps@pks.im>
---
 Documentation/BreakingChanges.txt | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/Documentation/BreakingChanges.txt b/Documentation/BreakingChanges.txt
index 68ad42d805..62695ec2e1 100644
--- a/Documentation/BreakingChanges.txt
+++ b/Documentation/BreakingChanges.txt
@@ -102,6 +102,19 @@ Cf. <2f5de416-04ba-c23d-1e0b-83bb655829a7@zombino.com>,
 
 === Removals
 
+* Support for grafting commits has long been superseded by git-replace(1).
+  Grafts are inferior to replacement refs:
++
+  ** Grafts are a local-only mechanism and cannot be shared across
+     repositories.
+  ** Grafts can lead to hard-to-diagnose problems when transferring objects
+     between repositories.
++
+The grafting mechanism has been marked as outdated since e650d0643b (docs: mark
+info/grafts as outdated, 2014-03-05) and will be removed.
++
+Cf. <20140304174806.GA11561@sigill.intra.peff.net>.
+
 == Superseded features that will not be deprecated
 
 Some features have gained newer replacements that aim to improve the design in

-- 
2.45.2.457.g8d94cfb545.dirty