Add contributing.html covering building FFmpeg, submitting patches via Forgejo, the review process, and writing FATE tests for libavutil, libavfilter, and libavcodec.
Sidebar nav left unchanged to avoid breaking bookmarks. Signed-off-by: marcos ashton <[email protected]> --- Makefile | 2 +- src/contributing | 378 +++++++++++++++++++++++++++++++++++++++++ src/contributing_js | 0 src/contributing_title | 1 + 4 files changed, 380 insertions(+), 1 deletion(-) create mode 100644 src/contributing create mode 100644 src/contributing_js create mode 100644 src/contributing_title diff --git a/Makefile b/Makefile index dd681e4..4f5c187 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ # ffmpeg.org HTML generation from source files -SRCS = about bugreports consulting contact donations documentation download \ +SRCS = about bugreports consulting contact contributing donations documentation download \ olddownload index legal shame security spi archive HTML_TARGETS = $(addsuffix .html,$(addprefix htdocs/,$(SRCS))) diff --git a/src/contributing b/src/contributing new file mode 100644 index 0000000..f19150b --- /dev/null +++ b/src/contributing @@ -0,0 +1,378 @@ +<p> + This page covers everything a first-time contributor needs to get + started: building FFmpeg, submitting patches, understanding code review, + and writing tests. +</p> + +<p> + For the full developer reference, see + <a href="developer.html">Developer Documentation</a> and + <a href="git-howto.html">Using Git to Develop FFmpeg</a>. +</p> + +<br> + +<h3 id="BuildSetup"> + <span class="pull-right"> + <i class="fa fa-wrench"></i> + </span> + Building FFmpeg</h3> + +<p> + Clone the repository and build: +</p> + +<pre> +git clone https://git.ffmpeg.org/ffmpeg.git +cd ffmpeg +./configure +make -j$(nproc)</pre> + +<p> + This builds ffmpeg, ffplay, and ffprobe. Run + <code>./configure --help</code> to see all options. +</p> + +<p> + For development, you probably want debug symbols and test coverage: +</p> + +<pre> +./configure --toolchain=gcov --assert-level=2 +make -j$(nproc)</pre> + +<p> + Verify your build: +</p> + +<pre> +./ffmpeg -version</pre> + +<br> + +<h3 id="SubmittingPatches"> + <span class="pull-right"> + <i class="fa fa-code-fork"></i> + </span> + Submitting Patches</h3> + +<p> + The preferred way to submit patches is through + <a href="https://code.ffmpeg.org/FFmpeg/FFmpeg/pulls";>Forgejo</a> + at code.ffmpeg.org. You can also send patches to the + <a href="https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel/";>ffmpeg-devel</a> + mailing list using <code>git format-patch</code> or + <code>git send-email</code>. +</p> + +<p> + GitHub pull requests are not part of the review process and will be ignored. +</p> + +<p><strong>Via Forgejo (recommended)</strong></p> + +<ol> + <li>Create an account at + <a href="https://code.ffmpeg.org";>code.ffmpeg.org</a>.</li> + <li>Fork the FFmpeg repository.</li> + <li>Push your branch to your fork.</li> + <li>Open a pull request against the main FFmpeg repository.</li> +</ol> + +<p><strong>Via mailing list</strong></p> + +<p> + Generate and send patches: +</p> + +<pre> +git format-patch origin/master +git send-email *.patch --to [email protected]</pre> + +<p> + Subscribe to ffmpeg-devel first. Patches from non-subscribers are held + for moderation and may be delayed. See + <a href="git-howto.html">Using Git to Develop FFmpeg</a> for + setup instructions. +</p> + +<p><strong>Commit message format</strong></p> + +<p> + The first line must follow this format: +</p> + +<pre> +area/component: short description of what changed</pre> + +<p> + Then a blank line, then the body explaining why the change is needed. + The diff shows what changed; the message should explain why. + End with a Signed-off-by line (<code>git commit -s</code>). +</p> + +<p> + Full example: +</p> + +<pre> +avcodec/libx264: fix memory leak in parameter parsing + +The options dictionary was not freed on the error path when +x264_param_parse() returned a failure code. + +Signed-off-by: Your Name <[email protected]></pre> + +<p> + Keep the first line under 72 characters. Each patch should be a single + logical change. Do not mix cosmetic changes with functional changes. + Run <code>tools/patcheck</code> on your patch before sending. +</p> + +<br> + +<h3 id="ReviewProcess"> + <span class="pull-right"> + <i class="fa fa-comments"></i> + </span> + The Review Process</h3> + +<p> + Every patch is reviewed by other developers, whether you submit via + Forgejo or the mailing list. Here is what to expect: +</p> + +<ol> + <li>A reviewer reads your patch and leaves comments. This may take + a few days. If you have not heard back after a week, send a + polite reminder or ask on <code>#ffmpeg-devel</code> on + <a href="https://libera.chat/";>Libera Chat</a>.</li> + <li>Address every comment. If you disagree with a suggestion, explain + your reasoning. Ignoring review comments will stall your patch.</li> + <li>Submit a revised version. On Forgejo, push to your branch. On the + mailing list, send a new version with <code>[PATCH v2]</code> in + the subject.</li> + <li>Repeat until the reviewer is satisfied. Simple patches may land + after one round. Larger patches often go through several + revisions.</li> + <li>Once approved, a developer with commit access pushes it to + master.</li> +</ol> + +<p> + Reviewing other people's patches is one of the best ways to get your + own patches reviewed faster. Everyone is welcome to review. +</p> + +<br> + +<h3 id="BeforeYouSubmit"> + <span class="pull-right"> + <i class="fa fa-check-square-o"></i> + </span> + Before You Submit</h3> + +<p> + Run the FATE test suite to make sure nothing is broken: +</p> + +<pre> +make fate</pre> + +<p> + If your patch changes expected output, update the reference files. + If your patch adds a new module (decoder, encoder, filter, muxer, + demuxer, parser, or bitstream filter), add a FATE test for it. +</p> + +<p> + Check your patch for common issues: +</p> + +<pre> +tools/patcheck your-patch.diff</pre> + +<p> + See the + <a href="developer.html#Patch-submission-checklist">Patch Submission Checklist</a> + for the full list. +</p> + +<br> + +<h3 id="WritingFATETests"> + <span class="pull-right"> + <i class="fa fa-flask"></i> + </span> + Writing FATE Tests</h3> + +<p> + FATE (FFmpeg Automated Testing Environment) is the regression test + suite. Tests are defined in <code>tests/fate/*.mak</code> files. + Reference outputs live in <code>tests/ref/fate/</code>. There are + three common patterns. +</p> + +<p><strong>C unit tests (libavutil)</strong></p> + +<p> + For testing utility functions, write a standalone C program that + exercises the API and prints results to stdout. +</p> + +<p> + Create the test at <code>libavutil/tests/yourtest.c</code>: +</p> + +<pre> +#include "libavutil/yourheader.h" + +int main(void) +{ + /* call the functions you want to test */ + printf("some_function: %s\n", result ? "OK" : "FAIL"); + return 0; +}</pre> + +<p> + Add it to <code>libavutil/Makefile</code>: +</p> + +<pre> +TESTPROGS += yourtest</pre> + +<p> + Register it in <code>tests/fate/libavutil.mak</code>: +</p> + +<pre> +FATE_LIBAVUTIL += fate-yourtest +fate-yourtest: libavutil/tests/yourtest$(EXESUF) +fate-yourtest: CMD = run libavutil/tests/yourtest$(EXESUF)</pre> + +<p> + Generate the reference output: +</p> + +<pre> +make fate-yourtest GEN=1</pre> + +<p> + This creates <code>tests/ref/fate/yourtest</code>. If your test only + checks exit codes and produces no meaningful stdout, add + <code>CMP = null</code>. +</p> + +<p><strong>Filter tests (libavfilter)</strong></p> + +<p> + Filter tests run a filter chain and compare per-frame CRC checksums + against a reference. They go in + <code>tests/fate/filter-audio.mak</code> or + <code>tests/fate/filter-video.mak</code>. +</p> + +<p> + Example for an audio filter: +</p> + +<pre> +FATE_AFILTER-$(call FILTERDEMDECENCMUX, YOURFILTER, WAV, PCM_S16LE, PCM_S16LE, WAV) += fate-filter-yourfilter +fate-filter-yourfilter: tests/data/asynth-44100-2.wav +fate-filter-yourfilter: SRC = $(TARGET_PATH)/tests/data/asynth-44100-2.wav +fate-filter-yourfilter: CMD = framecrc -i $(SRC) -af yourfilter</pre> + +<p> + The <code>FILTERDEMDECENCMUX</code> macro checks that all required + components are compiled in. The <code>framecrc</code> command computes + a CRC for each output frame. Generate the reference: +</p> + +<pre> +make fate-filter-yourfilter GEN=1</pre> + +<p> + This writes the reference to + <code>tests/ref/fate/filter-yourfilter</code>. To test multiple + format variants, add separate entries with suffixes like + <code>fate-filter-yourfilter-fltp</code>. +</p> + +<p><strong>Codec roundtrip tests (libavcodec)</strong></p> + +<p> + These encode audio or video with a codec, decode it back, and compare + the result against a reference. They live in + <code>tests/fate/acodec.mak</code>, + <code>tests/fate/vcodec.mak</code>, or a codec-specific + <code>.mak</code> file. +</p> + +<p> + The generic template in <code>tests/fate/acodec.mak</code> handles + most audio codecs. To use it, add a single line: +</p> + +<pre> +FATE_ACODEC_LOSSLESS-$(call ENCDEC, YOURCODEC, WAV) += yourcodec</pre> + +<p> + This encodes <code>tests/data/asynth-44100-2.wav</code>, decodes it + back to PCM, and compares against + <code>tests/ref/acodec/yourcodec</code>. +</p> + +<p> + For codecs that need custom options or lossy comparison: +</p> + +<pre> +FATE_ACODEC-$(call ENCDEC, YOURCODEC, WAV) += fate-acodec-yourcodec +fate-acodec-yourcodec: CMD = enc_dec_pcm yourformat wav s16le $(SRC) -c:a yourcodec -b:a 128k +fate-acodec-yourcodec: REF = $(SRC) +fate-acodec-yourcodec: CMP = stddev +fate-acodec-yourcodec: CMP_TARGET = 500</pre> + +<p> + <code>CMP = stddev</code> allows lossy comparison. The + <code>CMP_TARGET</code> value is the maximum allowed standard + deviation between original and decoded samples. +</p> + +<br> + +<h3 id="GettingHelp"> + <span class="pull-right"> + <i class="fa fa-life-saver"></i> + </span> + Getting Help</h3> + +<div class="well"> + <div class="list-group"> + <a class="list-group-item" href="irc://irc.libera.chat/ffmpeg-devel"> + <strong>#ffmpeg-devel on Libera Chat</strong><br> + Real-time discussion about FFmpeg development. Good for quick + questions and checking on patch status. + </a> + <a class="list-group-item" href="https://lists.ffmpeg.org/mailman/listinfo/ffmpeg-devel/";> + <strong>ffmpeg-devel mailing list</strong><br> + Patch submission, review, and development discussion. + Subscribe before posting. + </a> + <a class="list-group-item" href="https://code.ffmpeg.org";> + <strong>Forgejo (code.ffmpeg.org)</strong><br> + The preferred platform for submitting pull requests. + </a> + <a class="list-group-item" href="https://trac.ffmpeg.org/wiki";> + <strong>FFmpeg Wiki</strong><br> + Community-maintained documentation, guides, and how-tos. + </a> + </div> <!-- list-group --> +</div> <!-- well --> + +<p> + See also: + <a href="developer.html">Developer Documentation</a>, + <a href="git-howto.html">Using Git to Develop FFmpeg</a>, and + <a href="fate.html">FATE</a>. +</p> diff --git a/src/contributing_js b/src/contributing_js new file mode 100644 index 0000000..e69de29 diff --git a/src/contributing_title b/src/contributing_title new file mode 100644 index 0000000..cde9230 --- /dev/null +++ b/src/contributing_title @@ -0,0 +1 @@ +Contributing to FFmpeg \ No newline at end of file -- 2.53.0 _______________________________________________ ffmpeg-devel mailing list -- [email protected] To unsubscribe send an email to [email protected]
