Contributing: explain Patchwork

Add general guidelines for using Patchwork, as we heavily rely on it
nowadays.

v2:

- mention also Xwayland and libinput patch management
- reword "if not found in Patchwork"
- reword "Not applicable"
- mention pwclient

Cc: Bryce Harrington <bryce@osg.samsung.com>
Cc: Olivier Fourdan <ofourdan@redhat.com>
Signed-off-by: Pekka Paalanen <pekka.paalanen@collabora.co.uk>
Reviewed-by: Bryce Harrington <bryce@osg.samsung.com>
Reviewed-by: Olivier Fourdan <ofourdan@redhat.com>

diff --git a/doc/Contributing b/doc/Contributing
index 39c3e39..fe90614 100644 (file)
--- a/doc/Contributing
+++ b/doc/Contributing
@@ -30,6 +30,81 @@ cope with the way git log presents them.
 
 See [2] for a recommend reading on writing commit messages.
 
+
+== Tracking patches and following up ==
+
+Patchwork is used for tracking patches to Wayland and Weston:
+http://patchwork.freedesktop.org/project/wayland/list/
+
+Xwayland patches are tracked with the Xorg project, not here.
+
+Libinput patches, even though they use the same mailing list as Wayland, are
+not tracked in the Wayland Patchwork.
+
+The following applies only to Wayland and Weston.
+
+If a patch is not found in Patchwork, there is a high possibility for it to be
+forgotten. Patches attached to bug reports or not arriving to the mailing list
+because of e.g. subscription issues will not be in Patchwork because Patchwork
+only collects patches sent to the list.
+
+When you send a revised version of a patch, it would be very nice to mark your
+old patch as superseded (or rejected, if that is applicable). You can change
+the status of your own patches by registering to Patchwork - ownership is
+identified by email address you use to register. Updating your patch status
+appropriately will help maintainer work.
+
+The following patch states are found in Patchwork:
+
+  New
+       Patches under discussion or not yet processed.
+
+  Under review
+       Mostly unused state.
+
+  Accepted
+       The patch is merged in the master branch upstream, as is or slightly
+       modified.
+
+  Rejected
+       The idea or approach is rejected and cannot be fixed by revising
+       the patch.
+
+  RFC
+       Request for comments, not meant to be merged as is.
+
+  Not applicable
+       The email was not actually a patch, or the patch is not for Wayland or
+       Weston. Libinput patches are usually automatically ignored by Wayland
+       Patchwork, but if they get through, they will be marked as Not
+       applicable.
+
+  Changes requested
+       Reviewers determined that changes to the patch are needed. The
+       submitter is expected to send a revised version. (You should
+       not wait for your patch to be set to this state before revising,
+       though.)
+
+  Awaiting upstream
+       Mostly unused as the patch is waiting for upstream actions but
+       is not shown in the default list, which means it is easy to
+       overlook.
+
+  Superseded
+       A revised version of the patch has been submitted.
+
+  Deferred
+       Used mostly during freeze periods before releases, to temporarily
+       hide patches that cannot be merged during a freeze.
+
+Note, that in the default listing, only patches in New or Under review are
+shown.
+
+There is also a command line interface to Patchwork called 'pwclient', see
+http://patchwork.freedesktop.org/project/wayland/
+for links where to get it and the sample .pwclientrc for Wayland/Weston.
+
+
 == Coding style ==
 
 You should follow the style of the file you're editing. In general, we