ffmpeg-doc.texi

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. Watch out especially 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; @})}).
@end itemize

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
bugs).

Comments: use the JavaDoc/Doxygen 
format (see examples below) so that a documentation
can be generated automatically. All non trivial functions should have a comment
above it explaining what the function does, even if its just one sentance.
All Structures and their member variables should be documented too.
@example
/**
 * @@file mpeg.c
 * mpeg codec.
 * @@author ...
 */

/**
 * Summary sentance.
 * more text ...
 * ...
 */
typedef struct Foobar@{
    int var1; /**< var1 description */
    int var2; ///< var2 description
    /** var3 description */
    int var3;
@} Foobar;

/**
 * Summary sentance.
 * 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, too, then commit. If your code has problems
   (portability, exploits 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-dev mailing list. Do not remove
   functionality from the code. Just improve!
   
   Note: Redundant code can be removed
@item
   Do not commit changes to the build system (Makefiles, configure script)
   which change behaviour, 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-dev 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 indention throughout ffmpeg would be consistant (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 
   move it to the right)! or do so in a seperate commit
@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-dev (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
   a patch to ffmpeg-dev instead.
@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-dev, 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.
@item
    Never write to not allocated memory, never write over the end of arrays, 
    always check values read from some untrusted source before using them as index
    into an array or otherwise risky things.
@end enumerate

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 mailinglist
  Do NOT remove & readd a file - it will kill the changelog!!!!

@section Submitting patches

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 :-)

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 wont be trashed during 
transmission) to the ffmpeg-devel mailinglist, see 
@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 isnt c99 compliant
and has no lrint()')

We reply to all patches submitted and either apply or reject with some
explanation why, but sometimes we are quite busy so it can take a week or 2

@section Regression tests

Before submitting a patch (or committing with CVS), you should at least
test that you did not break anything.

The regression test build a synthetic video stream and a synthetic
audio stream. Then these are encoded then decoded with all codecs or
formats. The CRC (or MD5) of each generated file is recorded in a
result file. Then a 'diff' is launched with the reference results and
the result file.

The regression test then goes 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 regression tests results. In
this case, the regression tests reference results shall be modified
accordingly].

@bye