diff mbox series

[FFmpeg-devel,v2,1/3] doc/developer.texi: Improvements in Submitting patches section.

Message ID 20200712215301.24889-1-mstamat@gmail.com
State New
Headers show
Series [FFmpeg-devel,v2,1/3] doc/developer.texi: Improvements in "Submitting patches" section.
Related show

Checks

Context Check Description
andriy/default pending
andriy/make success Make finished
andriy/make_fate success Make fate finished

Commit Message

Manolis Stamatogiannakis July 12, 2020, 9:52 p.m. UTC
- Documentation for adding a roll-counter.
 - Mention the possibility to manualy supersede/withdraw patches on
   patchwork.

Signed-off-by: Manolis Stamatogiannakis <mstamat@gmail.com>
---
 doc/developer.texi | 41 +++++++++++++++++++++++++++++------------
 1 file changed, 29 insertions(+), 12 deletions(-)
diff mbox series

Patch

diff --git a/doc/developer.texi b/doc/developer.texi
index b33cab0fc7..585c37d241 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -491,18 +491,31 @@  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.
-
-Your patch will be reviewed on the mailing list. You will likely be asked
+You can check the most recently received patches on
+@url{https://patchwork.ffmpeg.org, patchwork}.
+If your patch does not show up, its mime type likely was wrong.
+
+If you need to manually manage your patch (e.g. urgently mark it as as
+"Superseded", or "Withdrawn") you can do so by
+@uref{https://patchwork.ffmpeg.org/register/, registering for a patchwork account}.
+Note that this is not generally required, as patch management on patchwork
+is largely automated. But there are case where manual patch management is
+desired. For example, if you have started working on extensive changes
+on your patch, and you don't want people to spend more time reviewing the
+old version.
+
+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, you should 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. While this is not
+a strict requirement, it is a commonly followed good practice.
 
 @chapter New codecs or formats checklist
 
@@ -563,7 +576,15 @@  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}?
+
+@item
+If you are submitting a revised patch, did you increment the roll-counter
+with @code{-v <n>}?
+
+@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 +597,6 @@  Did you provide a clear git commit log message?
 @item
 Is the patch against latest FFmpeg git master branch?
 
-@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?