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

[Manolis Stamatogiannakis]

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.
+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.
 
 @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?
-- 
2.17.1