[PATCH] Makefile: add pending semantic patches
- Date: Thu, 8 Nov 2018 12:52:55 -0800
- From: Stefan Beller <sbeller@xxxxxxxxxx>
- Subject: [PATCH] Makefile: add pending semantic patches
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.
Makefile | 7 +++--
contrib/coccinelle/README | 60 +++++++++++++++++++++++++++++++++++++++
2 files changed, 65 insertions(+), 2 deletions(-)
diff --git a/Makefile b/Makefile
index b08d5ea258..e5abfe4cef 100644
@@ -2739,9 +2739,12 @@ endif
echo ' ' SPATCH result: $@; \
-coccicheck: $(addsuffix .patch,$(wildcard contrib/coccinelle/*.cocci))
+coccicheck: $(addsuffix .patch,$(filter-out %.pending.cocci,$(wildcard contrib/coccinelle/*.cocci)))
+# 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
@@ -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.