README

   1 patchq is an email patch processing service which can monitor mailing
   2 list(s) for single patches or a series of patches, run tests on them
   3 ("does it compile", "does it pass the test suite"), and then sends a
   4 follow up email with the results.
   5
   6 It requires:
   7
   8  - Python 2
   9    (because we need to run on RHEL 6 which doesn't have python3-pika)
  10
  11  - python-pika (https://pypi.python.org/pypi/pika)
  12
  13  - A RabbitMQ server running somewhere on your network.
  14    You have to open port 5672 on the server, and provide the
  15    hostname of the server in ‘config.py’.
  16
  17  - Procmail or similar to feed email into the system.
  18
  19 To understand how patchq works, please read these blog posts:
  20
  21  - https://rwmj.wordpress.com/2017/07/06/patch-review-and-message-brokers/
  22
  23 Installation:
  24
  25  - There is no Makefile and nothing to build or install.  You can run
  26    everything from the local directory.
  27
  28  - Edit ‘config.py’ to configure a few things.
  29
  30  - Write some tests!  For every test listed in the ‘config.tests’
  31    list, you will need to write a corresponding ‘test-name.sh’.  Don't
  32    forget to make it executable.  See also: ‘perform-tests.py’.
  33
  34  - Run ‘./create-queues.py’ to set up the RabbitMQ exchanges, queues
  35    and other objects.  All RabbitMQ objects are prefixed by
  36    ‘patchq_...’, so to reverse this script you just have to delete
  37    everything in RabbitMQ with that prefix.
  38
  39  - If you want, you can manually test that everything works:
  40
  41      * Run ‘rabbitmqctl list_queues‘ => All queues should have 0 messages.
  42
  43      * Save some patch series into an mbox and inject them:
  44            ./inject-mbox.py mbox
  45
  46      * ‘rabbitmqctl list_queues’ should show the number of injected
  47        emails in the ‘patchq_input’ queue.
  48
  49      * Run ‘./threader.py’ which should combine single emails into
  50        threads and move all the patches to ‘patchq_test_*’.  If you
  51        check again with ‘rabbitmqctl list_queues’ you should see one
  52        message per patch series in every test queue.
  53
  54      * Run ‘./perform-tests.py’ which should start testing.
  55
  56      * Modify ‘config.py’ so that ‘reply_override’ is set to your own
  57        email address and run ‘./send-reports.py’.  This should send
  58        out report emails to you containing the results of the tests.
  59        Once you are happy that report emails are correct, you can set
  60        ‘reply_override’ to ‘None’ for production use.
  61
  62      * Run ‘./drain-queues.py’ to drop any messages remaining in all
  63        the queues, if you need to.
  64
  65      * Note because of the wonders of message brokers, you can run
  66        email, threader and testing on different hosts or a single
  67        host.
  68
  69  - Set up cron jobs:
  70
  71      * Set up a cron job to run ‘./threader.py’ periodically.  At
  72        least once every hour for light usage, and more often for
  73        mailing lists with heavy traffic.
  74
  75      * Set up a cron job to run ‘./perform-tests.py’ on your test
  76        system(s).  You can run different tests on different machines
  77        if you want.  Read the script to see how it works.
  78
  79      * Set up a cron job to run ‘./send-reports.py’ periodically.
  80
  81  - Set up procmail (or equivalent) to pick up emails sent to the
  82    mailing list and inject them into patchq.  See ‘procmail-example’
  83    for some ideas.
  84
  85 This code is released under the GNU General Public License v2 or any
  86 later version.  See ‘COPYING’ for details.
  87
  88 Development:
  89
  90  - Written by Richard W.M. Jones
  91
  92  - Send patches to the virt-tools mailing list:
  93    https://www.redhat.com/mailman/listinfo/virt-tools-list
  94
  95 To do:
  96
  97  - Handle multiple mailing lists and projects.
  98
  99  - Allow dependencies between tests (ie. test if the code compiles
 100    first before running other tests).
 101
 102 Similar projects:
 103
 104  - The 0-day test service is a very comprehensive set of tests
 105    which are run on kernel trees and patches posted to LKML.
 106    https://01.org/lkp/documentation/0-day-test-service
 107
 108  - https://github.com/patchew-project/patchew
 109    Developed and used by the qemu project.