On Wed, Apr 12, 2023 at 08:05:55PM +0000, Glen Choo via GitGitGadget wrote: > From: Glen Choo <chooglen@xxxxxxxxxx> > > This isn't set in stone; we expect this to be updated as the project > evolves. > > Signed-off-by: Glen Choo <chooglen@xxxxxxxxxx> > --- > 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
