summaryrefslogtreecommitdiff
path: root/contrib/coccinelle
diff options
context:
space:
mode:
authorLibravatar Junio C Hamano <gitster@pobox.com>2018-11-19 16:24:41 +0900
committerLibravatar Junio C Hamano <gitster@pobox.com>2018-11-19 16:24:41 +0900
commit0722553177966441376d7cf3c7ed664e00f92d14 (patch)
treefd1dcd6464345ac1a018a4dae1ee4ffc602be430 /contrib/coccinelle
parentMerge branch 'js/test-git-installed' (diff)
parentcoccicheck: introduce 'pending' semantic patches (diff)
downloadtgif-0722553177966441376d7cf3c7ed664e00f92d14.tar.xz
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
Diffstat (limited to 'contrib/coccinelle')
-rw-r--r--contrib/coccinelle/README41
1 files changed, 41 insertions, 0 deletions
diff --git a/contrib/coccinelle/README b/contrib/coccinelle/README
index 9c2f8879c2..f0e80bd7f0 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.