[PATCH wayland] Contributing: explain Patchwork

[Bryce Harrington]

On Mon, Sep 21, 2015 at 10:41:59AM +0300, Pekka Paalanen wrote:
> From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> 
> Add general guidelines for using Patchwork, as we heavily rely on it
> nowadays.
> 
> Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> ---
>  doc/Contributing | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 59 insertions(+)
> 
> diff --git a/doc/Contributing b/doc/Contributing
> index 39c3e39..4668f48 100644
> --- a/doc/Contributing
> +++ b/doc/Contributing
> @@ -30,6 +30,65 @@ 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/
> +
> +When you submit a patch, make sure it appears in the Patchwork list. Otherwise
> +there is a high possibility it will be forgotten.

TBH, patchwork seems to be quite reliable about tracking submitted
patches, so personally I don't think we need to trouble contributors to
have to check patchwork.  Maybe a more useful phrasing might be:

If you're wondering about the status on a patch you submitted, you can
doublecheck that it's listed in the Patchwork list.  If it isn't, then
there's a high possibility it will be forgotten.  Often, we remove
unlanded patches from the queue if there are changes needed.

> +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.

Currently we have a dozen patches marked Under review...

I wonder if we could make better use of this 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 patch is malformed, or not for Wayland or Weston.

Maybe explicitly say that Xwayland and libinput patches are set as Not
applicable?

I don't think I've ever set a malformed patch to Not applicable; rather
I would tell the submitter what the problem was, and then set it to
Changes Requested.  If it was a complete disaster I'd probably just mark
it Rejected.

> +  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.

Bryce

>  == Coding style ==
>  
>  You should follow the style of the file you're editing. In general, we
> -- 
> 2.4.6
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel