[PATCH] doc: refresh the Aiaiai overview text

Mon Feb 3 10:27:12 EST 2014

From: Artem Bityutskiy <artem.bityutskiy at linux.intel.com>

Rename the 'README.announcement' file to descriptive 'Overview.txt'. Refresh
its contents too. This file is supposed to give general information about what
Aiaiai is.

Signed-off-by: Artem Bityutskiy <artem.bityutskiy at linux.intel.com>
---
 doc/Overview.txt        | 66 +++++++++++++++++++++++++++++++++++++
 doc/README.announcement | 87 -------------------------------------------------
 2 files changed, 66 insertions(+), 87 deletions(-)
 create mode 100644 doc/Overview.txt
 delete mode 100644 doc/README.announcement

diff --git a/doc/Overview.txt b/doc/Overview.txt
new file mode 100644
index 0000000..06230dc
--- /dev/null
+++ b/doc/Overview.txt
@@ -0,0 +1,66 @@
+Aiaiai is a tool for validating Linux kernel patches using various available
+open-source tools. Aiaiai is useful for both subsystem maintainers and
+kernel developers.
+
+Aiaiai usage scenarios include:
+
+1. a developer has a patch-set which he/she wants to validate before submitting
+   to the maintainer or the subsystem mailing list
+2. a subsystem maintainer validates incoming patches before merging them to the
+   subsystem kernel tree
+
+Aiaiai roughly works as follows.
+
+1. Build the kernel before applying the patch-set and after applying the
+   patch-set.
+2. Run the following static analysis tools while building: sparse, smatch,
+   coccinelle, cppcheck.
+3. Compare the resulting build logs in a smart way (taking into account line
+   number changes, etc)
+3. Report about new gcc warnings and coccinelle/sparse/smatch/cppcheck
+   complaints. If checkpatch.pl has any complaints, they are also reported by
+   Aiaiai.
+
+Here is an example of Aiaiai report.
+
+--------------------------------------------------------------------------------
+
+1  Successfully built configuration "my_defconfig,i386", results:
+2
+3  --- before_patching.log
+4  +++ after_patching.log
+5  @@ @@
+6  -drivers/staging/cruft/my_drv.c: In function ‘my_pool_destroy’:
+7  -drivers/staging/cruft/my_drv.c:165:22: warning: variable ‘test1’ set but not used [-Wunused-but-set-variable]
+8  @@ @@
+9  +drivers/staging/cruft/my_drv.c: In function ‘my_event_handler’:
+10 +drivers/staging/cruft/my_drv.c:311:36: warning: unused variable ‘reg’ [-Wunused-variable]
+11 +drivers/staging/cruft/my_drv.c:1001:1-7: preceding lock on line 837 [coccinelle]
+12 +drivers/staging/cruft/my_drv.c:834 my_int_data(12) warn: variable dereferenced before check 'priv' (see line 827) [smatch]
+
+--------------------------------------------------------------------------------
+
+o Line 1 says that configuration "my_defconfig" for architecture i386 has been
+  built (so the patch-set compiles).
+o Starting from line 3 we have a diff of 2 build logs - before and after
+  patching.
+o Lines 6 and 7 tell that the patch-set eliminated a warning, which is very
+  welcome.
+o Lines 9 and 10 tell that the patch-set introduced a gcc warning, which is
+  less welcome.
+o Line 11 a complaint form coccinelle about locking. Worth looking closer.
+  The coccinelle scripts that are part of the Linux kernel do not usually
+  produce many false positives.
+o Line 12 tells that smatch has a complaint.
+
+Additionally, Aiaiai runs the bisectability test when there is more than one
+patch. It applies patches one-by-one, compiles at each step, and reports if
+compilation breaks.
+
+Aiaiai also runs checkpatch.pl for the whole patch-set (squashed) and
+every individual patch.
+
+Following are the currently implemented ways of using Aiaiai.
+1. Just run 'aiaiai-test-patchset' from console
+2. Attach Aiaiai to a mailing list using the e-mail front-end
+3. Attach Aiaiai to gerrit using a the Jenkins gerrit notifications plugin.
diff --git a/doc/README.announcement b/doc/README.announcement
deleted file mode 100644
index 42a6ad9..0000000
--- a/doc/README.announcement
+++ /dev/null
@@ -1,87 +0,0 @@
-Hi,
-
-I here is a tool which I find very helpful for subsystem maintainers and
-individual developers. This tool checks patches or patch-sets using various
-existing tools and reports new issues.
-
-The main thing it does is:
-1. Build the kernel before the patch and after the patch
-2. Compare 2 build logs
-3. Report about _new_ gcc warnings, coccinelle/spatch/smatch/cppcheck
-   complaints.
-
-For example, you can feed Aiaiai a patch-set, and it may report something
-like this:
-
---------------------------------------------------------------------------------
-
-1  Successfully built configuration "my_defconfig,i386", results:
-2
-3  --- before_patching.log
-4  +++ after_patching.log
-5  @@ @@
-6  -drivers/staging/cruft/my_drv.c: In function ‘my_pool_destroy’:
-7  -drivers/staging/cruft/my_drv.c:165:22: warning: variable ‘test1’ set but not used [-Wunused-but-set-variable]
-8  @@ @@
-9  +drivers/staging/cruft/my_drv.c: In function ‘my_event_handler’:
-10 +drivers/staging/cruft/my_drv.c:311:36: warning: unused variable ‘reg’ [-Wunused-variable]
-11 +drivers/staging/cruft/my_drv.c:1001:1-7: preceding lock on line 837 [coccinelle]
-12 +drivers/staging/cruft/my_drv.c:834 my_int_data(12) warn: variable dereferenced before check 'priv' (see line 827) [smatch]
-
---------------------------------------------------------------------------------
-
-Line 1 says that configuration my_defconfig for architecture i386 has been built,
-so the patch-set is at least compilable.
-
-Starting from line 3 we have a diff of 2 build logs - before and after patching.
-
-Lines 6 and 7 tell that the patch-set eliminated a warning - which is very welcome.
-
-Lines 9 and 10 tell that the patch-set introduced a gcc warning - not good.
-
-Line 11 tells that the patch made coccinelle complain about locking - worth checking
-as coccinelle scripts we have in the kernel are rather high quality.
-
-Line 12 tells that smatch has a complaint - also worth looking if this is a
-false-positive or not.
-
-Additionally, Aiaiai runs the bisectability tests when the patch-set contains
-more than one patch. It applies patches one-by-one and compiles at each step,
-and will report if compilation breaks.
-
-Aiaiai also checks if the patch changes a defconfig file, and if it does, it will
-verify that it is changed properly (make savedefconfig was used).
-
-And Aiaiai also runs checkpatch.pl for the whole patch-set (squashed) and
-every individual patch.
-
-Aiaiai also includes scripts which may be used to attach it to an e-mail address,
-so that when you can send patches to this e-mail address, and it will respond
-with test results.
-
-E.g., I use Aiaiai to verify incoming patches for the MTD subsystem since recently.
-I have small helper scripts which run Aiaiai for several configurations and
-architectures (i386, x86_64, ia64, ppc64, arm, mips). This makes me feel "safe"
-when I apply patches to my l2-mtd.git' tree. I do this also for UBIFS and UBI
-now.
-
-The README file contains more information:
-http://git.infradead.org/users/dedekind/aiaiai.git/blob/refs/heads/master:/README
-
-Sorry if this stuff is not very user-friendly - feel free to ask questions and
-send patches.
-
-You can find Aiaiai here:
-git://git.infradead.org/users/dedekind/aiaiai.git
-Gitweb: http://git.infradead.org/users/dedekind/aiaiai.git
-
-Credits:
-* Intel and my colleagues
-* Kirill Shutemov - he started writing this stuff, review, gave ideas, etc
-* Alexey Gladkov and other AltLinux guys for libshell
-  (git://git.altlinux.org/people/legion/packages/libshell.git)
-* Al Viro for the remapper
-  (git://git.kernel.org/pub/scm/linux/kernel/git/viro/remap.git)
-* Julia Lawall for amending coccinelle kernel patches to meet Aiaiai needs
-* Dan Carpenter for amending smatch to meet Aiaiai needs
-* Eric Melski for the serialize-log idea
-- 
1.8.5.3


