- Main text split to two sections.
- Detailed checklist for new codecs or formats demoted to section.
- Detailed checklist for patch submission demoted to section.
Signed-off-by: Manolis Stamatogiannakis <msta...@gmail.com>
---
doc/developer.texi | 64 +++++++++++++++++++++++++++++++---------------
1 file changed, 44 insertions(+), 20 deletions(-)
diff --git a/doc/developer.texi b/doc/developer.texi
index 585c37d241..c47d23e349 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -457,31 +457,49 @@ Finally, keep in mind the immortal words of Bill and Ted,
@anchor{Submitting patches}
@chapter Submitting patches
-First, read the @ref{Coding Rules} above if you did not yet, in particular
+@anchor{patch guidelines}
+@section Guidelines for preparing a patch
+
+The @strong{absolute minimum} you have to do before submitting a patch are the
+following:
+
+@enumerate
+@item Carefully read the @ref{Coding Rules} above if you did not yet, in
particular
the rules regarding patch submission.
-When you submit your patch, please use @code{git format-patch} or
-@code{git send-email}. We cannot read other diffs :-).
+@item Make sure your commit messages accurately describe the changes made
+(e.g. 'replaces lrint by lrintf') and why these changes are made (e.g.
+'*BSD isn't C99 compliant and has no lrint()').
-Also please do not submit a patch which contains several unrelated changes.
-Split it into separate, self-contained pieces. This does not mean splitting
-file by file. Instead, make the patch as small as possible while still
-keeping it as a logical unit that contains an individual change, even
-if it spans multiple files. This makes reviewing your patches much easier
-for us and greatly increases your chances of getting your patch applied.
+@item Make sure you use @code{git format-patch} or @code{git send-email} to
prepare
+your patch. We cannot read other diffs :-).
+
+@item Run the @ref{Regression tests, regression tests} before submitting a
patch
+in order to verify it does not cause unexpected problems.
-Use the patcheck tool of FFmpeg to check your patch.
-The tool is located in the tools directory.
+@item If you send your patches with an external email client
+(i.e. not @code{git send-email}), make sure to send each patch as a separate
+email. Do not attach several patches to the same email!
-Run the @ref{Regression tests} before submitting a patch in order to verify
-it does not cause unexpected problems.
+@item Do not submit a patch which contains several unrelated changes.
+@end enumerate
+
+Additionally, it is also important that each patch is logically
+self-contained. I.e. each patch should be as small as possible,
+while still containing a meaningful individual change.
+Patches spanning multiple files are perfectly fine, as long as they can
+be seen as a single logical unit.
-It also helps quite a bit if you tell us what the patch does (for example
-'replaces lrint by lrintf'), and why (for example '*BSD isn't C99 compliant
-and has no lrint()')
+Following these guidelines makes reviewing your patches much easier
+for us and greatly increases your chances of getting your patch applied.
+To further reduce the chance that you will need to revise your patch,
+it is also recommended to go through the detailed
+@ref{patch submission checklist, patch} and
+@ref{new codec format checklist, new codec or format}
+checklists.
-Also please if you send several patches, send each patch as a separate mail,
-do not attach several unrelated patches to the same mail.
+@anchor{patch submission process}
+@section Patch submission and revision process
Patches should be posted to the
@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, ffmpeg-devel}
@@ -517,7 +535,8 @@ 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
+@anchor{new codec format checklist}
+@section New codecs or formats checklist
@enumerate
@item
@@ -569,7 +588,8 @@ Did you make sure it compiles standalone, i.e. with
@end enumerate
-@chapter Patch submission checklist
+@anchor{patch submission checklist}
+@section Patch submission checklist
@enumerate
@item
@@ -594,6 +614,10 @@ of @dfn{sign-off}.
@item
Did you provide a clear git commit log message?
+@item
+Did you use the @code{patcheck} tool of FFmpeg to check your patch
+for common issues? E.g. @code{tools/patcheck *.patch}.
+
@item
Is the patch against latest FFmpeg git master branch?
--
2.17.1
_______________________________________________
ffmpeg-devel mailing list
ffmpeg-devel@ffmpeg.org
https://ffmpeg.org/mailman/listinfo/ffmpeg-devel
To unsubscribe, visit link above, or email
ffmpeg-devel-requ...@ffmpeg.org with subject "unsubscribe".
