Re: [PATCH 2/2] cocci: codify authoring and reviewing practices

["SZEDER Gábor" <szeder.dev@gmail.com>]

On Wed, Apr 12, 2023 at 08:05:55PM +0000, Glen Choo via GitGitGadget wrote:
> From: Glen Choo <chooglen@google.com>
> 
> This isn't set in stone; we expect this to be updated as the project
> evolves.
> 
> Signed-off-by: Glen Choo <chooglen@google.com>
> ---
>  contrib/coccinelle/README | 23 +++++++++++++++++++++++
>  1 file changed, 23 insertions(+)
> 
> diff --git a/contrib/coccinelle/README b/contrib/coccinelle/README
> index 9b28ba1c57a..055e3622e5c 100644
> --- a/contrib/coccinelle/README
> +++ b/contrib/coccinelle/README
> @@ -92,3 +92,26 @@ that might be useful to developers.
>  
>     The absolute times will differ for you, but the relative speedup
>     from caching should be on that order.
> +
> +== Authoring and reviewing coccinelle changes
> +
> +* When introducing and applying a new .cocci file, both the Git changes and
> +  .cocci file should be reviewed.
> +
> +* Reviewers do not need to be coccinelle experts. To give a Reviewed-By, it is
> +  enough for the reviewer to get a rough understanding of the proposed rules by
> +  comparing the .cocci and Git changes, then checking that understanding
> +  with the author.
> +
> +* Conversely, authors should consider that reviewers may not be coccinelle
> +  experts. The primary aim should be to make .cocci files easy to understand,
> +  e.g. by adding comments or by using rules that are easier to understand even
> +  if they are less elegant.
> +
> +* .cocci rules should target only the problem it is trying to solve; "collateral
> +  damage" is not allowed.
> +
> +* .cocci files used for refactoring should be temporarily kept in-tree to aid

How should such semantic patches be kept in-tree?
As .pending.cocci?  Then I think it would be better to point this out
here.  Or as a "regular" semantic patch?  Then I'm not sure I agree
with this recommendation, but perhaps a commit message explaining the
reasoning behind this would help me make up my mind :)

It might also be worth mentioning that before submitting a new
semantic patch developers should consider its cost-benefit ratio, in
particular its effect on the runtime of 'make coccicheck', in the hope
that we can avoid another 'unused.cocci' fiasco.

> +  the refactoring of out-of-tree code (e.g. in-flight topics). They should be
> +  removed when enough time has been given for others to refactor their code,
> +  i.e. ~1 release cycle.
> -- 
> gitgitgadget