@emph{any patch you make must be published}. The best way to proceed is
to send your patches to the FFmpeg mailing list.
+@section Contributing
+
+There are 3 ways by which code gets into ffmpeg.
+@itemize @bullet
+@item Submiting Patches to the main developer mailing list
+ see @ref{Submitting patches} for details.
+@item Directly commiting changes to the main tree.
+@item Commiting 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
+before they are commited. And they should follow the @ref{Coding Rules}.
+The developer making the commit and the author are responsible for their changes
+and should try to fix issues their commit causes.
+
@anchor{Coding Rules}
@section Coding Rules
accept patches to remove their use unless they absolutely do not impair
clarity and performance.
-All code must compile with GCC 2.95 and GCC 3.3. Currently, FFmpeg also
-compiles with several other compilers, such as the Compaq ccc compiler
-or Sun Studio 9, and we would like to keep it that way unless it would
-be exceedingly involved. To ensure compatibility, please do not use any
+All code must compile with recent versions of GCC and a number of other
+currently supported compilers. To ensure compatibility, please do not use
additional C99 features or GCC extensions. Especially watch out for:
@itemize @bullet
@item
All structures and their member variables should be documented, too.
@example
/**
- * @@file mpeg.c
+ * @@file
* MPEG codec.
* @@author ...
*/
Always fill out the commit log message. Describe in a few lines what you
changed and why. You can refer to mailing list postings if you fix a
particular bug. Comments such as "fixed!" or "Changed it." are unacceptable.
+ Recommanded format:
+ area changed: Short 1 line description
+
+ details describing what and why and giving references.
@item
- If you apply a patch by someone else, include the name and email address in
- the log message. Since the ffmpeg-cvslog mailing list is publicly
- archived you should add some SPAM protection to the email address. Send an
+ Make sure the author of the commit is set correctly. (see git commit --author)
+ If you apply a patch, send an
answer to ffmpeg-devel (or wherever you got the patch from) saying that
you applied the patch.
@item
Note, these rules are mostly borrowed from the MPlayer project.
+@anchor{Submitting patches}
@section Submitting patches
-First, (@pxref{Coding Rules}) above if you did not yet.
+First, read the @ref{Coding Rules} above if you did not yet, in particular
+the rules regarding patch submission.
-When you submit your patch, try to send a unified diff (diff '-up'
-option). We cannot read other diffs :-)
+When you submit your patch, please use @code{git format-patch} or
+@code{git send-email}. We cannot read other diffs :-)
Also please do not submit a patch which contains several unrelated changes.
Split it into separate, self-contained pieces. This does not mean splitting
Use the patcheck tool of FFmpeg to check your patch.
The tool is located in the tools directory.
-Run the regression tests before submitting a patch so that you can
-verify that there are no big problems.
+Run the @ref{Regression Tests} before submitting a patch in order to verify
+it does not cause unexpected problems.
Patches should be posted as base64 encoded attachments (or any other
encoding which ensures that the patch will not be trashed during
If it depends on a parser or a library, did you add that dependency in
configure?
@item
- Did you "git add" the appropriate files before committing?
+ Did you @code{git add} the appropriate files before committing?
+@item
+ Did you make sure it compiles standalone, i.e. with
+ @code{configure --disable-everything --enable-decoder=foo}
+ (or @code{--enable-demuxer} or whatever your component is)?
@end enumerate
+
@section patch submission checklist
@enumerate
@item
- Does 'make fate' pass with the patch applied?
+ Does @code{make fate} pass with the patch applied?
@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://kerneltrap.org/files/Jeremy/DCO.txt} for the meaning
of sign off.
+@item
+ 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-dev?
+ 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
@item
Lines with similar content should be aligned vertically when doing so
improves readability.
+@item
+ Consider to add a regression test for your code.
+@item
+ If you added YASM code please check that things still work with --disable-yasm
@end enumerate
@section Patch review process
We will review all submitted patches, but sometimes we are quite busy so
especially for large patches this can take several weeks.
+If you feel that the review process is too slow and you are willing to try to
+take over maintainership of the area of code you change then just clone
+git master and maintain the area of code there. We will merge each area from
+where its best maintained.
+
When resubmitting patches, please do not make any significant changes
not related to the comments received during review. Such patches will
be rejected. Instead, submit significant changes or new features as
Before submitting a patch (or committing to the repository), you should at least
test that you did not break anything.
-The regression tests build a synthetic video stream and a synthetic
-audio stream. These are then encoded and decoded with all codecs or
-formats. The CRC (or MD5) of each generated file is recorded in a
-result file. A 'diff' is launched to compare the reference results and
-the result file. The output is checked immediately after each test
-has run.
-
-The regression tests then go on to test the FFserver code with a
-limited set of streams. It is important that this step runs correctly
-as well.
-
-Run 'make test' to test all the codecs and formats. Commands like
-'make regtest-mpeg2' can be used to run a single test. By default,
-make will abort if any test fails. To run all tests regardless,
-use make -k. To get a more verbose output, use 'make V=1 test' or
-'make V=2 test'.
-
-Run 'make fulltest' to test all the codecs, formats and FFserver.
+Running 'make fate' accomplishes this, please see @file{doc/fate.txt} for details.
[Of course, some patches may change the results of the regression tests. In
this case, the reference results of the regression tests shall be modified