Describe patchwork work flow in README_maintainer

1 files changed, 83 insertions, 0 deletions

diff --git a/README_maintainer b/README_maintainer
index 07a9788..76a0391 100644
--- a/README_maintainer
+++ b/README_maintainer
@@ -7,6 +7,89 @@
 This document describes the tasks the Org-mode maintainer has to do
 and how they are performed.
 
+* Working with patchwork
+
+John Wiegley is running a patchwork server that looks at the
+emacs-orgmode mailing list and extracts patches.  The maintainer and
+his helpers should work through such patches, give feedback on them
+and apply the ones which are good and done.
+
+I have found that the best workflow for this is using the pw script by
+Nate Case, with the modifications for Org-mode made by John Wiegley
+and Carsten Dominik.  The correct version of this script that should
+be used with Org mode is distributed in the UTILITIES directory of the
+Org mode distribution.  Here is the basic workflow for this.
+
+** Access to the patchwork server
+
+If you want to work on patchwork patches, you need write access at the
+patchwork server.  You need to contact John Wiegley to get this
+access.
+
+There is a web interface to look at the patches and to change the
+status of patches.  This interface is self-explanatory.  There is also
+a command line script which can be very convenient to use.
+
+** Testing patches
+
+To start testing a patch, first assign it to yourself
+
+: pw update -s "Under Review" -d DELEGATE-NAME NNN
+
+where =NNN= is a patch number and =DELEGATE-NAME= is your user name on
+the patchwork server.
+
+The get the patch into a branch:
+
+: pw branch NNN
+
+This will create a local topic branch in your git repository with the
+name =t/patchNNN=.  You will also be switched to the branch so that
+you can immediately start testing it.  Quite often small amends need
+to be made, or documentation has to be added.  Also, many contributors
+do not yet provide the proper ChangeLog-like entries in the commit
+message for the patch.  As a maintainer, you have two options here.
+Either ask the contributor to make the changes and resubmit the patch,
+or fix it yourself.  In principle, asking to contributor to change the
+patch until it is complete is the best route, because it will educate
+the contributor and minimize the work for the maintainer.  However,
+sometimes it can be less hassle to fix things directly and commit the
+changes to the same branch =t/patchNNN=.
+
+If you ask the contributor to make the changes, the patch should be
+marked on the patchwork server as "changes requested".
+
+: pw update -s "Changed Requested" -m "What to change" NNN
+
+This will sand an email to the contributor and the mailing list with a
+request for changes.  The =-m= message should not be more than one
+sentence and describe the requested changes.  If you need to explain
+in more detail, write a separate email to the contributor.
+
+When a new version of the patch arrives, you mark the old one as
+superseded
+
+: pw update -s "Superseded" NNN
+
+and start working at the new one.
+
+** Merging a final patch
+
+Once the patch has been iterated and is final (including the
+ChangeLog-like entries in the commit message), it should be merged.
+The assumption here is that the final version of the patch is given by
+the HEAD state in the branch =t/patchNNN=.  To merge, do this:
+
+: pw merge -m "maintainer comment" NNN
+
+This will merge than patch into master, switch back to master and send
+an email to both contributor and mailing list stating that this change
+has been accepted, along with the comment given in the =-m= message.
+
+At some point you might then want to remove the topic branch
+
+: git -d t/patchNNN
+
 * Releases
 
 ** Main releases