[FFmpeg-devel] [RFC] doc: rewrite developer documentation
Paul B Mahol
onemda at gmail.com
Sat Aug 17 11:42:30 CEST 2013
On 8/17/13, Thilo Borgmann <thilo.borgmann at mail.de> wrote:
> Hi,
>
> I started with including some text about pull requests...
> I ended with a rewrite of almost the whole page, removing (IMHO) outdated
> info,
> removing redundant info, rewording many things.
> Most important for me is that this rewrite reorders things that seemed to
> have
> become too confusing in the old page.
>
> This is an RFC and not yet completely finished. If people tend to like the
> new
> design better than the old page, I will try to finish it and round it up
> for
> review. Please give me feedback for the overall redesign - if any detail
> information is missing in your eyes, this can be added later.
>
> -Thilo
>
>
>
>
> The following changes since commit
> faf7c356554d54be0ddb5f989791407e23753549:
>
> lavf/tee: add support for bitstream filtering (2013-08-16 17:58:58 +0200)
>
> are available in the git repository at:
>
> git at github.com:thiloborgmann/FFmpeg.git doc_developer
>
> for you to fetch changes up to 6f93ecdbf119640b2b0be34fd2a576c92c34d287:
>
> doc: rewrite developer documentation (2013-08-17 02:42:00 +0200)
>
> ----------------------------------------------------------------
> Thilo Borgmann (1):
> doc: rewrite developer documentation
>
> doc/developer.texi | 1000
> ++++++++++++++++++++++++++--------------------------
> 1 file changed, 493 insertions(+), 507 deletions(-)
>
> diff --git a/doc/developer.texi b/doc/developer.texi
> index b9951a4..8ac8e66 100644
> --- a/doc/developer.texi
> +++ b/doc/developer.texi
> @@ -9,76 +9,153 @@
> @contents
> - at chapter Developers Guide
> + at chapter Preface
> - at section Notes for external developers
> +This document is most useful for developers working on the FFmpeg
> libraries.
> +Developers using the FFmpeg libraries in their application should
> +refer to the doxygen @url{http://ffmpeg.org/doxygen/trunk/index.html, API
> documentation} and
> +check the examples in @file{doc/examples} and in the source code of
> +the provided FFmpeg tools to see how the public API is employed.
> -This document is mostly useful for internal FFmpeg developers.
> -External developers who need to use the API in their application should
> -refer to the API doxygen documentation in the public headers, and
> -check the examples in @file{doc/examples} and in the source code to
> -see how the public API is employed.
> -
> -You can use the FFmpeg libraries in your commercial program, but you
> -are encouraged to @emph{publish any patch you make}. In this case the
> -best way to proceed is to send your patches to the ffmpeg-devel
> -mailing list following the guidelines illustrated in the remainder of
> -this document.
> +You can also use the FFmpeg libraries in your commercial program, but
> +you have to conform to the license of the libraries.
> +You are also encouraged to @emph{publish any patch you make}.
> +In this case the best way to proceed is to send your patches to the
> + at uref{http://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, ffmpeg-devel
> mailing list}
> +following the guidelines illustrated in the remainder of this document.
> For more detailed legal information about the use of FFmpeg in
> external programs read the @file{LICENSE} file in the source tree and
> -consult @url{http://ffmpeg.org/legal.html}.
> +consult @url{http://ffmpeg.org/legal.html, FFmpeg License and Legal
> Considerations}.
> - at section Contributing
> -There are 3 ways by which code gets into ffmpeg.
> - at itemize @bullet
> - at item Submitting Patches to the main developer mailing list
> - see @ref{Submitting patches} for details.
> - at item Directly committing changes to the main tree.
> - at item Committing changes to a git clone, for example on github.com or
> - gitorious.org. And asking us to merge these changes.
> - at end itemize
> + at chapter Contributing to FFmpeg
> +
> +To contribute your work to FFmpeg you usually have to:
> +
> + at enumerate
> + at item @ref{implementation, Implement your contribution according to the
> coding
> rules.}
> + at item @ref{regression, Test for possible regressions and memory leaks and
> ensure robustness of your modifications.}
> + at item @ref{submission, Send a submission to the FFmpeg development mailing
> list.}
> + at item @ref{review, Iteratively update your submission according to the
> objections raised by reviewing FFmpeg developers.}
> + at item @ref{maintainership, Find your submission finally merged into the
> FFmpeg
> repository and claim maintainership for new files you created.}
> + at end enumerate
> +
> +The following sections correspond to the list above and form
> +a detailed guideline to help all contributors to comply to our
> +rules of development.
> +Following this guideline as close as possible is in the best interest
> +of every contributor, developer, maintainer and user of FFmpeg.
> -Whichever way, changes should be reviewed by the maintainer of the code
> -before they are committed. 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.
> - at anchor{Coding Rules}
> + at anchor{implementation}
> @section Coding Rules
> - at subsection Code formatting conventions
> +The main priority in FFmpeg is simplicity and small code size in order to
> +minimize the bug count.
> +The coding rules help with readability and maintainability of the code
> base
> +across heterogeneous systems, editors and developers.
> +
> + at subsection Programming Language and Features
> -There are the following guidelines regarding the indentation in files:
> +FFmpeg is written in the ISO C90 programming language.
> +Additionally, the following features from ISO C99 are utilized:
> @itemize @bullet
> - at item
> -Indent size is 4.
> + at item The @samp{inline} keyword
> + at item Single-line comments (@samp{//})
> + at item Designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
> + at item Compound literals (@samp{x = (struct s) @{ 17, 23 @};})
> + at end itemize
> - at item
> -The TAB character is forbidden outside of Makefiles as is any
> -form of trailing whitespace. Commits containing either will be
> -rejected by the git repository.
> +These features are supported by all compilers we care about, thus we will
> not
> +accept patches to remove their use unless they absolutely do not impair
> +clarity and performance.
> - at item
> -You should try to limit your code lines to 80 characters; however, do so
> if
> -and only if this improves readability.
> +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:
> +
> + at itemize @bullet
> + at item Mixing statements and declarations
> + at item Avoid @samp{long long}, use @samp{int64_t} instead
> + at item @samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or
> similar
> + at item GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})})
> @end itemize
> -The presentation is one inspired by 'indent -i4 -kr -nut'.
> -The main priority in FFmpeg is simplicity and small code size in order to
> -minimize the bug count.
> + at anchor{licenses}
> + at subsection Licenses
> +
> +Contributions are to be licensed under one of the following licenses in
> order
> of preference:
> + at enumerate
> + at item @uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1},
> + including an "or any later version" clause
> + at item @uref{http://www.gnu.org/licenses/gpl-2.0.html, GPL 2} including
> + an "or any later version" clause
> + at end enumerate
> +
> +For creating a new file, the appropriate license header should be copied
> +from another file of FFmpeg and not randomly copied and pasted from
> +somewhere else.
> +
> + at subsection Code formatting
> +
> + at itemize @bullet
> + at item Indent size is 4 characters.
> + at item The TAB character is forbidden outside of makefiles.
> + at item Trailing whitespaces are forbidden
> + at item You should try to limit your code lines to 80 characters.
> + However, do so if and only if this improves readability.
> + at end itemize
> +
> +In order to configure Vim to follow our code formatting conventions, paste
> +the following snippet into your @file{.vimrc}:
> + at example
> +" indentation rules for FFmpeg: 4 spaces, no tabs
> +set expandtab
> +set shiftwidth=4
> +set softtabstop=4
> +set cindent
> +set cinoptions=(0
> +" Allow tabs in Makefiles.
> +autocmd FileType make,automake set noexpandtab shiftwidth=8 softtabstop=8
> +" Trailing whitespace and tabs are forbidden, so highlight them.
> +highlight ForbiddenWhitespace ctermbg=red guibg=red
> +match ForbiddenWhitespace /\s\+$\|\t/
> +" Do not highlight spaces at the end of line while typing on that line.
> +autocmd InsertEnter * match ForbiddenWhitespace /\t\|\s\+\%#\@@<!$/
> + at end example
> +
> +For Emacs, add these roughly equivalent lines to your
> @file{.emacs.d/init.el}:
> + at example
> +(c-add-style "ffmpeg"
> + '("k&r"
> + (c-basic-offset . 4)
> + (indent-tabs-mode . nil)
> + (show-trailing-whitespace . t)
> + (c-offsets-alist
> + (statement-cont . (c-lineup-assignments +)))
> + )
> + )
> +(setq c-default-style "ffmpeg")
> + at end example
> - at subsection 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.
> -All structures and their member variables should be documented, too.
> -Avoid Qt-style and similar Doxygen syntax with @code{!} in it, i.e.
> replace
> - at code{//!} with @code{///} and similar. Also @@ syntax should be employed
> -for markup commands, i.e. use @code{@@param} and not @code{\param}.
> + at subsection Documentation
> +
> + at itemize @bullet
> + at item The API documentation is generated automatically using Doxygen
> format.
> + at item All functions of the public API should therefore feature a
> + Doxygen formatted comment covering all parameters and return values.
> + at item All nontrivial functions should have a comment above them explaining
> + what the function does, even if it is just one sentence.
> + at item All structures and their member variables should be documented.
> + at item Avoid Qt-style and similar Doxygen syntax with @code{!} in it, i.e.
> replace
> + @code{//!} with @code{///} and similar. Also @@ syntax should be
> employed
> + for markup commands, i.e. use @code{@@param} and not @code{\param}.
> + at end itemize
> @example
> /**
> @@ -92,12 +169,12 @@ for markup commands, i.e. use @code{@@param} and not
> @code{\param}.
> * more text ...
> * ...
> */
> -typedef struct Foobar@{
> +typedef struct FooBar@{
> int var1; /**< var1 description */
> int var2; ///< var2 description
> /** var3 description */
> int var3;
> -@} Foobar;
> +@} FooBar;
> /**
> * Summary sentence.
> @@ -110,82 +187,57 @@ int myfunc(int my_parameter)
> ...
> @end example
> - at subsection C language features
> -
> -FFmpeg is programmed in the ISO C90 language with a few additional
> -features from ISO C99, namely:
> + at subsection Naming Conventions
> @itemize @bullet
> - at item
> -the @samp{inline} keyword;
> -
> - at item
> - at samp{//} comments;
> -
> - at item
> -designated struct initializers (@samp{struct s x = @{ .i = 17 @};})
> -
> - at item
> -compound literals (@samp{x = (struct s) @{ 17, 23 @};})
> + at item All type names, like structs and enums, should always be written
> + in CamelCase.
> + at item All other names should always be composed using underscores (_).
> @end itemize
> -These features are supported by all compilers we care about, so we will
> not
> -accept patches to remove their use unless they absolutely do not impair
> -clarity and performance.
> -
> -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:
> -
> - at itemize @bullet
> - at item
> -mixing statements and declarations;
> + at example
> +typedef struct FooBar@{
> + int video_var1;
> + int audio_var2;
> + int subtitle_var3;
> +@} FooBar;
> - at item
> - at samp{long long} (use @samp{int64_t} instead);
> +int avfilter_get_video_buffer(AVFilterContext *filter_ctx, AVBuffer
> *out_buf);
> + at end example
> - at item
> - at samp{__attribute__} not protected by @samp{#ifdef __GNUC__} or similar;
> + at subsection Prefix Conventions
> - at item
> -GCC statement expressions (@samp{(x = (@{ int y = 4; y; @})}).
> + at itemize @bullet
> + at item Prefix: @code{<none>}
> + at itemize @bullet
> + @item Local variables
> + @item File-scope variables
> + @item Static functions
> @end itemize
> -
> - at subsection Naming conventions
> -All names should be composed with underscores (_), not CamelCase. For
> example,
> - at samp{avfilter_get_video_buffer} is an acceptable function name and
> - at samp{AVFilterGetVideo} is not. The exception from this are type names,
> like
> -for example structs and enums; they should always be in the CamelCase
> -
> -There are the following conventions for naming variables and functions:
> -
> + at item Prefix: @code{ff_}
> @itemize @bullet
> - at item
> -For local variables no prefix is required.
> -
> - at item
> -For file-scope variables and functions declared as @code{static}, no
> prefix
> -is required.
> -
> - at item
> -For variables and functions visible outside of file scope, but only used
> -internally by a library, an @code{ff_} prefix should be used,
> -e.g. @samp{ff_w64_demuxer}.
> -
> - at item
> -For variables and functions visible outside of file scope, used internally
> -across multiple libraries, use @code{avpriv_} as prefix, for example,
> - at samp{avpriv_aac_parse_header}.
> + @item Variables and functions visible outside of the file scope
> + which are used internally in the respective library, only.
> + at end itemize
> + at item Prefix: @code{avpriv_}
> + at itemize @bullet
> + @item Variables and functions visible outside of the file scope
> + which are used internally in multiple libraries.
> + at end itemize
> + at item Prefix: @code{av_}, @code{avformat_}, @code{avcodec_}, @code{swr_},
> ...
> + at itemize @bullet
> + at item Public symbols.
> + In addition to the prefix @code{av_}, each library
> + also has its own prefix for public symbols, corresponding to the
> + name of the library. For example @code{avformat_} for libavformat,
> + @code{avcodec_} for libavcodec, @code{swr_} for libswresample, etc.
> + Check the existing code and choose names accordingly.
> + at end itemize
> + at end itemize
> - at item
> -Each library has its own prefix for public symbols, in addition to the
> -commonly used @code{av_} (@code{avformat_} for libavformat,
> - at code{avcodec_} for libavcodec, @code{swr_} for libswresample, etc).
> -Check the existing code and choose names accordingly.
> Note that some symbols without these prefixes are also exported for
> -retro-compatibility reasons. These exceptions are declared in the
> - at code{lib<name>/lib<name>.v} files.
> - at end itemize
> +retro-compatibility reasons.
> +These exceptions are declared in the @code{lib<name>/lib<name>.v} files.
> Furthermore, name space reserved for the system should not be invaded.
> Identifiers ending in @code{_t} are reserved by
> @@ -198,298 +250,316 @@ symbols. If in doubt, just avoid names starting
> with
> @code{_} altogether.
> @subsection Miscellaneous conventions
> @itemize @bullet
> - at item
> -fprintf and printf are forbidden in libavformat and libavcodec,
> -please use av_log() instead.
> + at item Logging
> + at itemize @bullet
> + @item Since @code{fprintf} and @code{printf} are forbidden in
> + libavformat and libavcodec, use @code{av_log} instead.
> + at end itemize
> + at item Casting
> + at itemize @bullet
> + @item Casts should be avoided. Use only if necessary.
> + at end itemize
> + at item Parentheses
> + at itemize @bullet
> + @item Unneeded parentheses should be avoided if they don't
> + make the code easier to understand.
> + at end itemize
> + at end itemize
> - at item
> -Casts should be used only when necessary. Unneeded parentheses
> -should also be avoided if they don't make the code easier to understand.
> +
> + at anchor{regression}
> + at section FATE Regression tests and hardening
> +
> + at itemize
> + at item Run FATE to test for regressions introduced by your modifications by
> + calling @code{make fate}.
> + at item Optionally, e.g. if your modifications allocate memory, configure
> FATE
> + to utilize valgrind for spotting bugs related to memory handling.
> + at item Optionally, e.g. if your modifications are related to any kind of
> input
> + bitstream handling, utilize a fuzzer program for hardening your
> code.
> @end itemize
> - at subsection Editor configuration
> -In order to configure Vim to follow FFmpeg formatting conventions, paste
> -the following snippet into your @file{.vimrc}:
> - at example
> -" indentation rules for FFmpeg: 4 spaces, no tabs
> -set expandtab
> -set shiftwidth=4
> -set softtabstop=4
> -set cindent
> -set cinoptions=(0
> -" Allow tabs in Makefiles.
> -autocmd FileType make,automake set noexpandtab shiftwidth=8 softtabstop=8
> -" Trailing whitespace and tabs are forbidden, so highlight them.
> -highlight ForbiddenWhitespace ctermbg=red guibg=red
> -match ForbiddenWhitespace /\s\+$\|\t/
> -" Do not highlight spaces at the end of line while typing on that line.
> -autocmd InsertEnter * match ForbiddenWhitespace /\t\|\s\+\%#\@@<!$/
> - at end example
> +For details about how to set up and run FATE, please refer to
> @url{fate.html}.
> -For Emacs, add these roughly equivalent lines to your
> @file{.emacs.d/init.el}:
> - at example
> -(c-add-style "ffmpeg"
> - '("k&r"
> - (c-basic-offset . 4)
> - (indent-tabs-mode . nil)
> - (show-trailing-whitespace . t)
> - (c-offsets-alist
> - (statement-cont . (c-lineup-assignments +)))
> - )
> - )
> -(setq c-default-style "ffmpeg")
> - at end example
> +Of course, some modifications may change the results of the regression
> tests.
> +In this case, the reference results of the regression tests shall be
> modified
> +accordingly.
> - at section Development Policy
> +Also, some modifications may require a new test sample to be included into
> the
> +FATE-suite.
> +This is usually the case if there is no muxer or encoder available to
> generate
> +an appropriate sample.
> +For that purpose, please create a sample that is as small as possible
> +while still testing all your modifications sufficiently.
> - at enumerate
> - at item
> -Contributions should be licensed under the
> - at uref{http://www.gnu.org/licenses/lgpl-2.1.html, LGPL 2.1},
> -including an "or any later version" clause, or, if you prefer
> -a gift-style license, the
> - at uref{http://www.isc.org/software/license/, ISC} or
> - at uref{http://mit-license.org/, MIT} license.
> - at uref{http://www.gnu.org/licenses/gpl-2.0.html, GPL 2} including
> -an "or any later version" clause is also acceptable, but LGPL is
> -preferred.
> +Once you have created a working fate test and fate sample, please include
> a
> +direct download link to your sample in your submission so that it can
> easily
> +be included.
> - at 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.
> +For hardening your code, you might utilize @code{tools/trasher}, the noise
> +bitstream filter, or other fuzzer programs like
> + at uref{http://caca.zoy.org/wiki/zzuf, zzuf}.
> +Your code should not crash, end in a (near) infinite loop, or allocate
> ridiculous
> +amounts of memory when fed with damaged data.
> - at item
> -The commit message should have a short first line in the form of
> -a @samp{topic: short description} as a header, separated by a newline
> -from the body consisting of an explanation of why the change is necessary.
> -If the commit fixes a known bug on the bug tracker, the commit message
> -should include its bug ID. Referring to the issue on the bug tracker does
> -not exempt you from writing an excerpt of the bug in the commit message.
> - at item
> -You do not 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.
> - at item
> -Do not commit unrelated changes together, split them into self-contained
> -pieces. Also do not forget that if part B depends on part A, but A does
> not
> -depend on B, then A can and should be committed first and separate from B.
> -Keeping changes well split into self-contained parts makes reviewing and
> -understanding them on the commit log mailing list easier. This also helps
> -in case of debugging later on.
> -Also if you have doubts about splitting or not splitting, do not hesitate
> to
> -ask/discuss it on the developer mailing list.
> + at anchor{submission}
> + at section Submitting your contribution
> - at item
> -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.
> -Do not remove functionality from the code. Just improve!
> + at itemize @bullet
> + at item Clone a local or remote git repository.
> + at item Commit your modifications in seperate, logically self-contained
> parts
> + and compose descriptive commit messages.
> + at item Generate patches or a pull-request based on your commits.
> + at item Verify the contents of your patches or pull-request.
> + at item Send your patches or pull-request to the
> + @uref{http://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel,
> ffmpeg-devel}
> + mailing list.
> + at end itemize
> -Note: Redundant code can be removed.
> +Cloning a local or remote git repository to generate patches
> +or pull-requests using the git tools helps us the most to review and
> +merge your work.
> +Any other form is most likely to be rejected.
> +
> +Committing your modifications in seperate, logically self-contained parts
> +does not mean splitting file by file.
> +Instead, make each commit 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 modifications much easier for us and greatly
> increases
> +the chances of getting your work merged.
> +
> +Composing descriptive commit messages includes to point out as clearly as
> possible
> +what this commit does (for example 'replaces lrint by lrintf'), and why it
> does
> +so (for example '*BSD isn't C99 compliant and has no lrint()').
This is simply not true.
> +Long commit messages should include a header in the form of
> +a @samp{topic: short description}, separated by a blank line
> +from the body consisting of the detailed description.
> +If a known bug is fixed, the commit message should also include its bug ID
> as
> +defined in the @url{https://trac.ffmpeg.org, bug tracker}.
> +
> +The following real-world commit message serves as a good example:
> + at example
> +configure: Only build ffserver if SA_RESAMPLE is available.
> - at 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.
> +QNX does not define SA_RESAMPLE (because it is not implemented).
> +Fixes ticket #2780.
> + at end example
> - at 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 do not.). If you really need to make
> -indentation changes (try to avoid this), separate them strictly from real
> -changes.
> +Once your modifications are commited into your local or remote repository,
> you
> +can generate patches or a pull-request based on your commits.
> +In case you want to create a pull-request, ensure that you have also pushed
> your
> +commits into your remote repository.@*
> +In order to create patches, please use: @code{git format-patch}@*
> +In order to create a pull-request, please use: @code{git request-pull -p}
> -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 (do not
> -move it to the right)! or do so in a separate commit
> +For verifying your submission, you can use @code{tools/patcheck} to check
> your
> +patches, if applicable.
> +At least, you should visually inspect any submission before actually
> sending it.
> - at 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.
> -Recommended format:
> -area changed: Short 1 line description
> +In order to send patches, please use: @code{git send-email} or @code{git
> imap-send}@*
> +In order to send a pull-request or cannot use the commands above, send
> +your submissions as base64-encoded attachments. This ensures that your
> +submission is not trashed during transmission.
> -details describing what and why and giving references.
> +If you are about to send several submissions, ensure to send each one as a
> +separate mail. Do not attach several unrelated submissions to the same
> mail.
> - at item
> -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.
> +We appreciate the use of the following prefixes for better orientation on
> the
> +mailing list.@*
> +To indicate that your submission shall be merged, please use:
> @code{[PATCH]}@*
> +To indicate that your submission shall be the base of a topic
> +related discussion (a Request For Comments), please use: @code{[RFC]}.
> - at item
> -When applying patches that have been discussed (at length) on the mailing
> -list, reference the thread in the log message.
> - at item
> -Do NOT commit to code actively maintained by others without permission.
> -Send a patch to ffmpeg-devel instead. If no one answers within a
> reasonable
> -timeframe (12h for build failures and security fixes, 3 days small
> changes,
> -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!
> + at anchor{review}
> + at section Reviewing process
> - at item
> -Subscribe to the ffmpeg-cvslog mailing list. 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.
> +Every submission will be reviewed on the
> + at uref{http://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel, ffmpeg-devel}
> +mailing list, unless they contain a
> +clear note that the patch is not for the git master branch.
> +You will likely be asked to make some changes and are expected to send in
> an
> +improved version that incorporates the requests from the review.
> +This process may go through several iterations.
> +Once your patch is deemed good enough, some developer will pick it up and
> +commit it to the official FFmpeg repository.
This is too vague.
[...]
More information about the ffmpeg-devel
mailing list