Newer
Older
@end itemize
These features are supported by all compilers we care about, so we won't
accept patches to remove their use unless they absolutely don't 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 don't use any
additional C99 features or GCC extensions. Especially watch out for:
@itemize @bullet
@item
mixing statements and declarations;
@item
@samp{long long} (use @samp{int64_t} instead);
@item
@samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
@item
GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
Indent size is 4. The TAB character should not be used.
The presentation is the one specified by 'indent -i4 -kr'.
Main priority in FFmpeg is simplicity and small code size (=less
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's just one sentence.
All structures and their member variables should be documented, too.
* @@file mpeg.c
* MPEG codec.
* @@author ...
*/
* Summary sentence.
* more text ...
* ...
*/
int var1; /**< var1 description */
int var2; ///< var2 description
/** var3 description */
int var3;
* Summary sentence.
* more text ...
* ...
* @@param my_parameter description of my_parameter
* @@return return value description
*/
int myfunc(int my_parameter)
...
@end example
fprintf and printf are forbidden in libavformat and libavcodec,
please use av_log() instead.
@node CVS Policy
@section CVS Policy
@enumerate
@item
You must not commit code which breaks FFmpeg! (Meaning unfinished but
enabled code which breaks compilation or compiles but does not work or
breaks the regression tests)
You can commit unfinished stuff (for testing etc), but it must be disabled
(#ifdef etc) by default so it does not interfere with other developers'
work.
@item
You don't have to over-test things. If it works for you, and you think it
should work for others, then commit. If your code has problems
(portability, triggers compiler bugs, unusual environment etc) they will be
reported and eventually fixed.
@item
Do not commit unrelated changes together, split them into self-contained
pieces.
@item
Do not change behavior of the program (renaming options etc) without
first discussing it on the ffmpeg-devel mailing list. Do not remove
@item
Do not commit changes to the build system (Makefiles, configure script)
which change behavior, defaults etc, without asking first. The same
applies to compiler warning fixes, trivial looking fixes and to code
maintained by other developers. We usually have a reason for doing things
the way we do. Send your changes as patches to the ffmpeg-devel mailing
list, and if the code maintainers say OK, you may commit. This does not
apply to files you wrote and/or maintain.
@item
We refuse source indentation and other cosmetic changes if they are mixed
with functional changes, such commits will be rejected and removed. Every
developer has his own indentation style, you should not change it. Of course
if you (re)write something, you can use your own style, even though we would
prefer if the indentation throughout FFmpeg was consistent (Many projects
force a given indentation style - we don't.). If you really need to make
indentation changes (try to avoid this), separate them strictly from real
changes.
NOTE: If you had to put if()@{ .. @} over a large (> 5 lines) chunk of code,
then either do NOT change the indentation of the inner part within (don't
@item
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.
@item
If you apply a patch by someone else, include the name and email address in
the CVS log message. Since the ffmpeg-cvslog mailing list is publicly
archived you should add some SPAM protection to the email address. Send an
answer to ffmpeg-devel (or wherever you got the patch from) saying that
you applied the patch.
@item
Do NOT commit to code actively maintained by others without permission. Send
@item
Subscribe to the ffmpeg-cvslog mailing list. The diffs of all CVS 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.
@item
Update the documentation if you change behavior or add features. If you are
unsure how best to do this, send a patch to ffmpeg-devel, the documentation
maintainer(s) will review and commit your stuff.
@item
Revert a commit ONLY in case of a big blunder like committing something not
intended to be committed or committing a wrong file, the wrong version of a
patch, CVS policy violation or broken code and you are going to recommit the
right thing immediately.
Never revert changes made a long time ago or buggy code. Fix it in the
normal way instead.
Never write to unallocated memory, never write over the end of arrays,
always check values read from some untrusted source before using them
as array index or other risky things.
We think our rules are not too hard. If you have comments, contact us.
Note, these rules are mostly borrowed from the MPlayer project.
@subsection Renaming/moving files or content of files
You CANNOT do that. Post a request for such a change to the mailing list
Do NOT remove & readd a file - it will kill the changelog!!!!
@section Submitting patches
Michael Niedermayer
committed
First, (@pxref{Coding Rules}) above if you didn't yet.
When you submit your patch, try to send a unified diff (diff '-up'
option). I cannot read other diffs :-)
Michael Niedermayer
committed
Also please do not submit patches which contain several unrelated changes.
Split them into individual self-contained patches; this makes reviewing
them much easier.
Run the regression tests before submitting a patch so that you can
verify that there are no big problems.
Patches should be posted as base64 encoded attachments (or any other
encoding which ensures that the patch won't be trashed during
@url{http://www1.mplayerhq.hu/mailman/listinfo/ffmpeg-devel}
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()')
We reply to all submitted patches and either apply or reject with some
explanation why, but sometimes we are quite busy so it can take a week or two.
@section Regression tests
Before submitting a patch (or committing to CVS), 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 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.
Run 'make fulltest' to test all the codecs, formats and FFserver.
[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
accordingly].
@bye