Francois Gouget : patches: Improve the documentation, particularly for the installation process.

[Alexandre Julliard]

Module: tools
Branch: master
Commit: 7e9eb2d3d0b023740abeaa28a15c0f04bc8378f9
URL:    http://source.winehq.org/git/tools.git/?a=commit;h=7e9eb2d3d0b023740abeaa28a...

Author: Francois Gouget 
Date:   Fri Mar  8 15:14:52 2013 +0100

patches: Improve the documentation, particularly for the installation process.

---

patches/doc/INSTALL.txt       |   77 +++++++++++++++++++++++++++++++++++++++++
 patches/doc/vhost_source.conf |   11 ++++++
 patches/expire                |    3 +-
 patches/filter                |    4 ++-
 patches/filter-testbot        |    3 +-
 patches/notify-bot            |    2 +-
 patches/update                |    3 +-
 patches/update-regressions    |    3 ++
 8 files changed, 101 insertions(+), 5 deletions(-)

diff --git a/patches/doc/INSTALL.txt b/patches/doc/INSTALL.txt
new file mode 100644
index 0000000..86b3dca
--- /dev/null
+++ b/patches/doc/INSTALL.txt
@@ -0,0 +1,77 @@
+1. Dependencies
+---------------
+
+- Text::CSV::Encoded (libtext-csv-encoded-perl)
+- Email::MIME (libemail-mime-perl)
+
+
+2. General setup
+----------------
+
+- Create a new user 'winehq'.
+- Clone Wine's tools repository to $HOME/tools (so this document
+  should be available as $HOME/tools/patches/README).
+- Create directory $HOME/opt/source/git. Run:
+    mkdir -p $HOME/opt/source/git
+- Clone the Wine repository to a new bare repository (it can be read-only).
+    cd $HOME/opt/source/git
+    git clone --bare git://source.winehq.org/git/wine.git
+- Arrange for the Wine source to be updated regularly. For instance:
+    0 * * * * cd $HOME/opt/source/git/wine.git && git fetch
+
+Apache setup:
+- Create the $HOME/opt/source directory. This is the root of the source website:
+    mkdir -p $HOME/opt/source
+- Create a new virtual host, use vhost_source.conf as a template.
+
+
+3. Setup for the LXR source site
+--------------------------------
+
+- FIXME: Document how to set up LXR in $HOME/opt/source.
+
+
+4. Setup for the patches site
+-----------------------------
+
+- Create the $HOME/opt/source/patches directory and copy patches.css there:
+    mkdir $HOME/opt/source/patches
+    cp patches.css $HOME/opt/source/patches
+- Create the $HOME/patches and $HOME/patches/OLD directories where the patch
+  data will live:
+    mkdir -p $HOME/patches/OLD
+- Arrange for the filter script to be fed the wine-patches emails. One way to
+  do so would be to subscribe the winehq user to the wine-patches mailing list
+  and to then add the following lines to the .procmailrc file:
+    :0
+    * ^List-Id: Wine Patch Submissions
+    {
+      :0 hbfw
+      | $HOME/tools/patches/filter
+      :0:
+      $HOME/patches/.
+    }
+- If you have a set of patch emails in the mbox format you can test with:
+  formail -ds procmail <mbox-file
+- Run update regularly to update the website:
+    */5 * * * * $HOME/tools/patches/update
+- Run expire regularly to delete old patches:
+    0 0 * * * $HOME/tools/patches/expire -v $HOME/patches
+
+To integrate with the WineTestBot also do the following:
+- Run the notify-bot script regularly to notify the WineTestBot when there are
+  new patches to test.
+    */5 * * * * $HOME/tools/patches/notify-bot <winetestbot-email-address>
+- Arrange for the filter-testbot script to be fed the WineTestBot emails. One
+  way to do so is to add the following lines to the .procmailrc file:
+    :0 bfw
+    * ^X-TestBot-Results:
+    | $HOME/tools/patches/filter-testbot
+
+
+
+5. Setup for the regressions site
+---------------------------------
+
+- Run update-regressions regularly. For instance:
+    0 * * * * $HOME/tools/patches/update-regressions
diff --git a/patches/doc/vhost_source.conf b/patches/doc/vhost_source.conf
new file mode 100644
index 0000000..30bfca5
--- /dev/null
+++ b/patches/doc/vhost_source.conf
@@ -0,0 +1,11 @@
+<VirtualHost *:80>
+  DocumentRoot /home/winehq/opt/source
+
+  ServerName source.example.com
+  ServerAdmin [e-mail]
+
+  <Directory /home/winehq/opt/source>
+    Order allow,deny
+    Allow from all
+  </Directory>
+</VirtualHost>
diff --git a/patches/expire b/patches/expire
index 05aee19..f143ab1 100755
--- a/patches/expire
+++ b/patches/expire
@@ -1,6 +1,7 @@
 #!/usr/bin/perl -w
 #
-# Patches expiration script
+# Deletes or archives 'old' patches. Note that the exact definition of 'old'
+# depends on the patch's status.
 #
 # Copyright 2009 Alexandre Julliard
 #
diff --git a/patches/filter b/patches/filter
index dbdb9ec..306787d 100755
--- a/patches/filter
+++ b/patches/filter
@@ -1,6 +1,8 @@
 #!/usr/bin/perl -w
 #
-# Filter a wine-patches submission.
+# Reformat a wine-patches email so it can be put in a file that the patches
+# site can link to. In particular this means only keeping the relevant
+# header fields and decoding / decompressing the patch.
 #
 # Copyright 2009 Alexandre Julliard
 #
diff --git a/patches/filter-testbot b/patches/filter-testbot
index 3c4e33b..844090c 100755
--- a/patches/filter-testbot
+++ b/patches/filter-testbot
@@ -1,6 +1,7 @@
 #!/usr/bin/perl -w
 #
-# Filter a testbot result report.
+# Process a testbot result email and generate the .testfail and .testbot
+# result files that the patches site uses / links to.
 #
 # Copyright 2010 Alexandre Julliard
 #
diff --git a/patches/notify-bot b/patches/notify-bot
index 104a496..9676c42 100755
--- a/patches/notify-bot
+++ b/patches/notify-bot
@@ -1,6 +1,6 @@
 #!/bin/sh
 #
-# Notify winetestbot of the arrival of new patches
+# Send an email to the WineTestBot to let it know of new patches.
 #
 # Copyright 2010 Alexandre Julliard
 #
diff --git a/patches/update b/patches/update
index f92a64c..c716354 100755
--- a/patches/update
+++ b/patches/update
@@ -1,6 +1,7 @@
 #!/usr/bin/perl -w
 #
-# Update the patches data and index file
+# Scans the local patches and their result files to rebuild the index file and
+# update the patches website.
 #
 # Copyright 2009 Alexandre Julliard
 #
diff --git a/patches/update-regressions b/patches/update-regressions
index 3a71509..3bc2fff 100755
--- a/patches/update-regressions
+++ b/patches/update-regressions
@@ -1,5 +1,8 @@
 #!/usr/bin/perl -w
 #
+# Grabs Bugzilla's data about known regressions and rebuilds the regressions
+# website index.
+#
 # Copyright 2011 Henri Verbeet
 # Copyright 2011 Alexandre Julliard
 #