Hi Patrick
Thanks for working on this, I've left a couple of small comments below
but I'm not sure they're worth a re-roll on their own. All of the
patches look sensible to me.
On 03/06/2024 10:28, Patrick Steinhardt wrote:
+The intent of this document is to track upcoming deprecations for the next
+major Git release. Furthermore, this document also tracks what will _not_ be
+deprecated. This is done such that the outcome of discussions documente both
+when the discussion favors deprecation, but also when it rejects a deprecation.
+
+Items should have a self-sufficient explanation why we want or do not want to
> +make the described change.
"self-sufficient explanation" strikes me as a slightly add turn of
phrase, maybe something like
Items should have a clear summary of the reasons why we do or do not
want to make the described change that can be easily understood
without having to read the mailing list discussions.
If there are alternatives to the changed feature,
+those alternatives should be pointed out to our users.
+
+All items should be accompanied by references to relevant mailing list threads
+where the deprecation was discussed. These references use message-IDs, which
+can visited via
+
+ https://lore.kernel.org/git/$message_id/
+
+to see the message and its surrounding discussion. Such a reference is there to
+make it easier for you to find how the project reached concensus on the
+described item back then.
+
+This is a living document as the environment surrounding the project changes
+over time. An earlier decision to deprecate or change something may need to be
+revisited from time to time. So do not take items on this list to mean "it is
+settled, do not waste our time bringing it up again".
We could possibly add "If circumstances change" to the start of the
second sentence to discourage repeated discussions of the same issue
when someone has a bee in their bonnet about a particular change but I
think we can probably handle that on the mailing list without any
changes here.
Best Wishes
Phillip
