From: SZEDER Gábor <szeder.dev@xxxxxxxxx> Add a description and place on how to use coccinelle for large refactorings that happen only once. Based-on-work-by: SZEDER Gábor <szeder.dev@xxxxxxxxx> Signed-off-by: Stefan Beller <sbeller@xxxxxxxxxx> --- I consider including this patch in a resend instead. It outlays the basics of such a new workflow, which we can refine later. Thanks, Stefan Makefile | 7 +++-- contrib/coccinelle/README | 60 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index b08d5ea258..e5abfe4cef 100644 --- a/Makefile +++ b/Makefile @@ -2739,9 +2739,12 @@ endif then \ echo ' ' SPATCH result: $@; \ fi -coccicheck: $(addsuffix .patch,$(wildcard contrib/coccinelle/*.cocci)) +coccicheck: $(addsuffix .patch,$(filter-out %.pending.cocci,$(wildcard contrib/coccinelle/*.cocci))) -.PHONY: coccicheck +# See contrib/coccinelle/README +coccicheck-pending: $(addsuffix .patch,$(wildcard contrib/coccinelle/*.pending.cocci)) + +.PHONY: coccicheck coccicheck-pending ### Installation rules diff --git a/contrib/coccinelle/README b/contrib/coccinelle/README index 9c2f8879c2..fa09d1abcc 100644 --- a/contrib/coccinelle/README +++ b/contrib/coccinelle/README @@ -1,2 +1,62 @@ This directory provides examples of Coccinelle (http://coccinelle.lip6.fr/) semantic patches that might be useful to developers. + +There are two types of semantic patches: + + * Using the semantic transformation to check for bad patterns in the code; + This is what the original target 'make coccicheck' is designed to do and + it is expected that any resulting patch indicates a regression. + The patches resulting from 'make coccicheck' are small and infrequent, + so once they are found, they can be sent to the mailing list as per usual. + + Example for introducing new patterns: + 67947c34ae (convert "hashcmp() != 0" to "!hasheq()", 2018-08-28) + b84c783882 (fsck: s/++i > 1/i++/, 2018-10-24) + + Example of fixes using this approach: + 248f66ed8e (run-command: use strbuf_addstr() for adding a string to + a strbuf, 2018-03-25) + f919ffebed (Use MOVE_ARRAY, 2018-01-22) + + These types of semantic patches are usually part of testing, c.f. + 0860a7641b (travis-ci: fail if Coccinelle static analysis found something + to transform, 2018-07-23) + + * Using semantic transformations in large scale refactorings throughout + the code base. + + When applying the semantic patch into a real patch, sending it to the + mailing list in the usual way, such a patch would be expected to have a + lot of textual and semantic conflicts as such large scale refactorings + change function signatures that are used widely in the code base. + A textual conflict would arise if surrounding code near any call of such + function changes. A semantic conflict arises when other patch series in + flight introduce calls to such functions. + + So to aid these large scale refactorings, semantic patches can be used, + using the process as follows: + + 1) Figure out what kind of large scale refactoring we need + -> This is usually done by another unrelated series. + 2) Create the sematic patch needed for the large scale refactoring + and store it in contrib/coccinelle/*.pending.cocci + -> The suffix containing 'pending' is important to differentiate + this case from the other use case of checking for bad patterns. + 3) Apply the semantic patch only partially, where needed for the patch series + that motivates the large scale refactoring and then build that series + on top of it. + By applying the semantic patch only partially where needed, the series + is less likely to conflict with other series in flight. + To make it possible to apply the semantic patch partially, there needs + to be mechanism for backwards compatibility to keep those places working + where the semantic patch is not applied. This can be done via a + wrapper function that has the exact name and signature as the function + to be changed. + + 4) Send the series as usual, including only the needed parts of the + large scale refactoring + + Later steps (not necessarily by the original author) are to apply the + semantic patch in a way that do not produce lots of conflicts, for example + by consulting `git diff --numstat origin/master..origin/pu` and the changes + of the semantic patch. -- 2.19.1.930.g4563a0d9d0-goog
