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

From: Phillip Wood <phillip.wood123@gmail.com>
Date: Jun 3, 2024, 14:08 UTC
Message-ID: <c2129c09-dd71-4cc7-802c-bf662db93435@gmail.com>
In-Reply-To: <67cb4de5cbbee7f7d4e22a7223a4838551956f26.1717402497.git.ps@pks.im>

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:

Show 6 quoted lines

> +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.

Show 17 quoted lines

> 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