Merge branch 'sb/cocci-pending'
A coding convention around the Coccinelle semantic patches to have
two classes to ease code migration process has been proposed and
its support has been added to the Makefile.
* sb/cocci-pending:
coccicheck: introduce 'pending' semantic patches
diff --git a/Makefile b/Makefile
index af873ae..1a44c81 100644
--- a/Makefile
+++ b/Makefile
@@ -2742,9 +2742,12 @@
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 9c2f887..f0e80bd 100644
--- a/contrib/coccinelle/README
+++ b/contrib/coccinelle/README
@@ -1,2 +1,43 @@
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;
+ The target 'make coccicheck' is designed to check for these patterns 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.
+ However we do not want to store them in the same place as the checks for
+ bad patterns, as then automated builds would fail.
+ That is why semantic patches 'contrib/coccinelle/*.pending.cocci'
+ are ignored for checks, and can be applied using 'make coccicheck-pending'.
+
+ This allows to expose plans of pending large scale refactorings without
+ impacting the bad pattern checks.
