diff --git a/README_maintainer b/README_maintainer index 07a978814..76a039109 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