[FFmpeg-devel] [RFC] doc: rewrite developer documentation

[Thilo Borgmann]

Am 17.08.13 11:42, schrieb Paul B Mahol:
> 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
>> [...]
>> +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.

This is taken as-is from the current page. I don't know if it's true or not but
can for sure be replaced by something more appropriate.

>> +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.

What lines exactly are you refering to with 'this'?
What aspects should be pointed out more clearly?

I take you're looking into the details that you're pleased with the redesign itself?

-Thilo