Commit 7fa951d330 for ffmpeg

commit 7fa951d330bdb2237816f0622eb46165da9714df
Author: Romain Beauxis <romain.beauxis@gmail.com>
Date:   Thu Nov 5 10:03:50 2026 -0600

    doc/developer: add a source tree layout section

    The section makes a file's path name what the file is and the logical group it belongs to.

    It sets the rules for subsystem directories, file names, includes, Makefiles and commits that move files.

diff --git a/doc/developer.texi b/doc/developer.texi
index 92ccedd381..5ab6dbee81 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -380,6 +380,74 @@ letter as they are reserved by the C standard. Names starting with @code{_}
 are reserved at the file level and may not be used for externally visible
 symbols. If in doubt, just avoid names starting with @code{_} altogether.

+@anchor{Source tree layout}
+@section Source tree layout
+
+A file's path tells the reader what the file is.
+It also tells the reader which logical group the file belongs to.
+The rules below follow from this principle.
+
+@subsection Directories
+
+A subsystem is the set of files implementing one format, codec or shared
+feature, for example Ogg or ID3v2.
+A subsystem made of more than one file lives in its own directory inside its
+library, for example @file{libavformat/ogg/}.
+A nested directory groups related files within a subsystem, for example the
+per-codec mappings (@code{struct ogg_codec}) in @file{libavformat/ogg/mapping/}.
+
+@subsection File names
+
+Inside a subsystem directory, file names drop the subsystem prefix.
+The directory already carries it.
+
+A file name states the file's role in full words, for example
+@file{demuxer.c}, @file{muxer.c}, @file{decoder.c}, @file{encoder.c},
+@file{parser.c}, @file{reader.c} or @file{writer.c}.
+Abbreviations would be ambiguous across libraries.
+For example, @samp{dec} means a decoder in libavcodec and a demuxer in
+libavformat.
+
+A header shared by a subsystem is named after it.
+It sits next to the subsystem's directory, for example @file{libavformat/id3v2.h}
+next to @file{libavformat/id3v2/}.
+Its include path then reads as the subsystem's name.
+
+Files that predate these rules keep their names until a commit moves them.
+
+@subsection Includes
+
+A file includes headers from its own directory by their bare name, for example
+@code{#include "mapping.h"}.
+It includes all other headers by their path from the source root, for example
+@code{#include "libavformat/ogg/mapping.h"}.
+The include path then names the group each header belongs to.
+
+@subsection Build system
+
+Each subsystem directory has its own @file{Makefile}.
+It lists the objects of the components the subsystem implements, with paths
+relative to the library, for example
+@code{OBJS-$(CONFIG_OGG_DEMUXER) += ogg/demuxer.o}.
+It also has a @code{clean::} rule for each of its directories.
+The library @file{Makefile} includes it.
+Other components list the subsystem objects they use in their own
+@file{Makefile}.
+
+@subsection Moving files
+
+A commit that moves files changes nothing else.
+It updates only what refers to the moved files: includes, Makefiles,
+@file{MAINTAINERS} and @file{.forgejo/CODEOWNERS}.
+This lets git's rename detection carry pending patches and backports across
+the move.
+Patches written against the old paths apply with @command{git am -3}.
+
+Renaming symbols to match the new layout happens in one commit after the move.
+That commit also realigns the lines the rename shifts.
+
+Each subsystem moves in its own commit.
+
 @section Miscellaneous conventions

 @itemize @bullet