[FFmpeg-devel] [PATCH v1 1/3] doc/developer.texi: Improvements in "Submitting patches" section.

[Nicolas George]

Manolis Stamatogiannakis (12020-07-05):
> The section has been expanded to outline how to manage patch revisions.
> ---
>  doc/developer.texi | 37 ++++++++++++++++++++++++++-----------
>  1 file changed, 26 insertions(+), 11 deletions(-)
> 
> diff --git a/doc/developer.texi b/doc/developer.texi
> index b33cab0fc7..dec27cb509 100644
> --- a/doc/developer.texi
> +++ b/doc/developer.texi
> @@ -491,18 +491,25 @@ as base64-encoded attachments, so your patch is not trashed during
>  transmission. Also ensure the correct mime type is used
>  (text/x-diff or text/x-patch or at least text/plain) and that only one
>  patch is inline or attached per mail.
> -You can check @url{https://patchwork.ffmpeg.org}, if your patch does not show up, its mime type
> -likely was wrong.
> +You can check the most recently received patches on
> + at url{https://patchwork.ffmpeg.org, patchwork}.
> +If your patch does not show up, its mime type likely was wrong.
>  
> -Your patch will be reviewed on the mailing list. You will likely be asked
> +Your patch will be reviewed on the mailing list. Give us a few days to react.
> +But if some time passes without reaction, send a reminder by email.
> +Your patch should eventually be dealt with. However, you will likely be asked
>  to make some changes and are expected to send in an improved version that
>  incorporates the requests from the review. This process may go through
>  several iterations. Once your patch is deemed good enough, some developer
>  will pick it up and commit it to the official FFmpeg tree.
>  
> -Give us a few days to react. But if some time passes without reaction,
> -send a reminder by email. Your patch should eventually be dealt with.
> -

> +When preparing an updated version of you patch, make sure you increment
> +its @emph{roll-counter}. This is achieved by adding a @code{-v <n>} argument
> +to @code{git format-patch}/@code{git send-email} commands.

I know many core developers do not bother with that, and I never found
these "v3" very useful: if I am not involved in the discussion, I will
not remember what number is the latest. And if I become involved in the
discussions, my mail client can sort the patch by date and I take the
latest.

> +Additionally, it is recommended to register for a
> + at uref{https://patchwork.ffmpeg.org, patchwork account}.
> +This will allow you to mark previous version of your patches as "Superseded",
> +and reduce the chance of someone spending time to review a stale patch.

Is interacting with Patchwork to become mandatory when submitting
patches?

There is this classic scenario:

1. People work on something.

2. Somebody sets up a tool to make the work easier.

3. People start relying on the tool.

4. The tool proves imperfect.

5. People are required extra work to go around the flaws of the tool.

6. Overall, the tool has made the work not easier but harder.

Are we going that way with Patchwork?

If I am required to log into a website and do maintenance each time I
send an updated patch, I will just send less updated patches. I am not
alone in this.

>  
>  @chapter New codecs or formats checklist
>  
> @@ -563,7 +570,19 @@ Did you make sure it compiles standalone, i.e. with
>  Does @code{make fate} pass with the patch applied?
>  
>  @item
> -Was the patch generated with git format-patch or send-email?
> +Was the patch generated with @code{git format-patch} or @code{git send-email}?
> +
> + at item
> +If you are submitting a revised patch, did you increment the roll-counter
> +with @code{-v <n>}?
> +
> + at item
> +If you are submitting a revised patch, did you marked previous versions of
> +the patch as "Superseded" on @uref{https://patchwork.ffmpeg.org/, patchwork}?
> +
> + at item
> +Are you subscribed to ffmpeg-devel?
> +(the list is subscribers only due to spam)
>  
>  @item
>  Did you sign-off your patch? (@code{git commit -s})
> @@ -576,10 +595,6 @@ Did you provide a clear git commit log message?
>  @item
>  Is the patch against latest FFmpeg git master branch?
>  
> - at item
> -Are you subscribed to ffmpeg-devel?
> -(the list is subscribers only due to spam)
> -
>  @item
>  Have you checked that the changes are minimal, so that the same cannot be
>  achieved with a smaller patch and/or simpler final code?

Regards,

-- 
  Nicolas George
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20200707/61af03ab/attachment.sig>