@contents
-@chapter Developers Guide
-
-@section Notes for external developers
+@chapter Notes for external developers
This document is mostly useful for internal FFmpeg developers.
External developers who need to use the API in their application should
external programs read the @file{LICENSE} file in the source tree and
consult @url{https://ffmpeg.org/legal.html}.
-@section Contributing
+@chapter Contributing
-There are 3 ways by which code gets into FFmpeg.
+There are 2 ways by which code gets into FFmpeg:
@itemize @bullet
-@item Submitting patches to the main developer mailing list.
+@item Submitting patches to the ffmpeg-devel mailing list.
See @ref{Submitting patches} for details.
@item Directly committing changes to the main tree.
-@item Committing changes to a git clone, for example on github.com or
- gitorious.org. And asking us to merge these changes.
@end itemize
Whichever way, changes should be reviewed by the maintainer of the code
and should try to fix issues their commit causes.
@anchor{Coding Rules}
-@section Coding Rules
+@chapter Coding Rules
-@subsection Code formatting conventions
+@section Code formatting conventions
There are the following guidelines regarding the indentation in files:
The main priority in FFmpeg is simplicity and small code size in order to
minimize the bug count.
-@subsection Comments
+@section Comments
Use the JavaDoc/Doxygen format (see examples below) so that code documentation
can be generated automatically. All nontrivial functions should have a comment
above them explaining what the function does, even if it is just one sentence.
...
@end example
-@subsection C language features
+@section C language features
FFmpeg is programmed in the ISO C90 language with a few additional
features from ISO C99, namely:
@item
compound literals (@samp{x = (struct s) @{ 17, 23 @};}).
+@item
+for loops with variable definition (@samp{for (int i = 0; i < 8; i++)});
+
+@item
+Variadic macros (@samp{#define ARRAY(nb, ...) (int[nb + 1])@{ nb, __VA_ARGS__ @}});
+
@item
Implementation defined behavior for signed integers is assumed to match the
expected behavior for two's complement. Non representable values in integer
GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
@end itemize
-@subsection Naming conventions
+@section Naming conventions
All names should be composed with underscores (_), not CamelCase. For example,
@samp{avfilter_get_video_buffer} is an acceptable function name and
@samp{AVFilterGetVideo} is not. The exception from this are type names, like
are reserved at the file level and may not be used for externally visible
symbols. If in doubt, just avoid names starting with @code{_} altogether.
-@subsection Miscellaneous conventions
+@section Miscellaneous conventions
@itemize @bullet
@item
should also be avoided if they don't make the code easier to understand.
@end itemize
-@subsection Editor configuration
+@section Editor configuration
In order to configure Vim to follow FFmpeg formatting conventions, paste
the following snippet into your @file{.vimrc}:
@example
(setq c-default-style "ffmpeg")
@end lisp
-@section Development Policy
+@chapter Development Policy
-@subsection Patches/Committing
+@section Patches/Committing
@subheading Licenses for patches must be compatible with FFmpeg.
Contributions should be licensed under the
@uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1},
1 week for big patches) then commit your patch if you think it is OK.
Also note, the maintainer can simply ask for more time to review!
-@subsection Code
+@section Code
@subheading API/ABI changes should be discussed before they are made.
Do not change behavior of the programs (renaming options etc) or public
API or ABI without first discussing it on the ffmpeg-devel mailing list.
always check values read from some untrusted source before using them
as array index or other risky things.
-@subsection Documentation/Other
+@section Documentation/Other
+@subheading Subscribe to the ffmpeg-devel mailing list.
+It is important to be subscribed to the
+@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, ffmpeg-devel}
+mailing list. Almost any non-trivial patch is to be sent there for review.
+Other developers may have comments about your contribution. We expect you see
+those comments, and to improve it if requested. (N.B. Experienced committers
+have other channels, and may sometimes skip review for trivial fixes.) Also,
+discussion here about bug fixes and FFmpeg improvements by other developers may
+be helpful information for you. Finally, by being a list subscriber, your
+contribution will be posted immediately to the list, without the moderation
+hold which messages from non-subscribers experience.
+
+However, it is more important to the project that we receive your patch than
+that you be subscribed to the ffmpeg-devel list. If you have a patch, and don't
+want to subscribe and discuss the patch, then please do send it to the list
+anyway.
+
@subheading Subscribe to the ffmpeg-cvslog mailing list.
-It is important to do this as the diffs of all commits are sent there and
-reviewed by all the other developers. Bugs and possible improvements or
-general questions regarding commits are discussed there. We expect you to
-react if problems with your code are uncovered.
+Diffs of all commits are sent to the
+@uref{https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-cvslog, ffmpeg-cvslog}
+mailing list. Some developers read this list to review all code base changes
+from all sources. Subscribing to this list is not mandatory.
@subheading Keep the documentation up to date.
Update the documentation if you change behavior or add features. If you are
We think our rules are not too hard. If you have comments, contact us.
-@section Code of conduct
+@chapter Code of conduct
Be friendly and respectful towards others and third parties.
Treat others the way you yourself want to be treated.
"Be excellent to each other."
@anchor{Submitting patches}
-@section Submitting patches
+@chapter Submitting patches
First, read the @ref{Coding Rules} above if you did not yet, in particular
the rules regarding patch submission.
send a reminder by email. Your patch should eventually be dealt with.
-@section New codecs or formats checklist
+@chapter New codecs or formats checklist
@enumerate
@item
@end enumerate
-@section patch submission checklist
+@chapter Patch submission checklist
@enumerate
@item
Was the patch generated with git format-patch or send-email?
@item
-Did you sign off your patch? (git commit -s)
-See @url{http://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git;a=blob_plain;f=Documentation/SubmittingPatches} for the meaning
-of sign off.
+Did you sign-off your patch? (@code{git commit -s})
+See @uref{https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/submitting-patches.rst, Sign your work} for the meaning
+of @dfn{sign-off}.
@item
Did you provide a clear git commit log message?
If the patch fixes a bug, did you provide enough information, including
a sample, so the bug can be reproduced and the fix can be verified?
Note please do not attach samples >100k to mails but rather provide a
-URL, you can upload to ftp://upload.ffmpeg.org.
+URL, you can upload to @url{https://streams.videolan.org/upload/}.
@item
Did you provide a verbose summary about what the patch does change?
of leaks, out of array accesses, etc.
@end enumerate
-@section Patch review process
+@chapter Patch review process
All patches posted to ffmpeg-devel will be reviewed, unless they contain a
clear note that the patch is not for the git master branch.
way to get everyone's patches reviewed sooner.
@anchor{Regression tests}
-@section Regression tests
+@chapter Regression tests
Before submitting a patch (or committing to the repository), you should at least
test that you did not break anything.
this case, the reference results of the regression tests shall be modified
accordingly].
-@subsection Adding files to the fate-suite dataset
+@section Adding files to the fate-suite dataset
When there is no muxer or encoder available to generate test media for a
specific test then the media has to be included in the fate-suite.
message or introductory message for the patch series that you post to
the ffmpeg-devel mailing list, a direct link to download the sample media.
-@subsection Visualizing Test Coverage
+@section Visualizing Test Coverage
The FFmpeg build system allows visualizing the test coverage in an easy
manner with the coverage tools @code{gcov}/@code{lcov}. This involves
measurements. You will need to rerun @code{make lcov} after running a
new test.
-@subsection Using Valgrind
+@section Using Valgrind
The configure script provides a shortcut for using valgrind to spot bugs
related to memory handling. Just add the option
your configure line instead.
@anchor{Release process}
-@section Release process
+@chapter Release process
FFmpeg maintains a set of @strong{release branches}, which are the
recommended deliverable for system integrators and distributors (such as
on the @strong{ffmpeg-devel} mailing list in time to allow forward planning.
@anchor{Criteria for Point Releases}
-@subsection Criteria for Point Releases
+@section Criteria for Point Releases
Changes that match the following criteria are valid candidates for
inclusion into a point release:
The order for checking the rules is (1 OR 2 OR 3) AND 4.
-@subsection Release Checklist
+@section Release Checklist
The release process involves the following steps:
projects / ffmpeg / blobdiff