Re: [PATCH v5 1/4] docs: introduce document to announce breaking changes

[Phillip Wood <phillip.wood123@gmail.com>]

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