[FFmpeg-devel] [PATCH 4/6] doc/developer: add a code behaviour section to development policy

[Anton Khirnov]

Document our longstanding de facto policies on things like correctness,
thread-safety, UB, etc.
---
 doc/developer.texi | 50 +++++++++++++++++++++++++++++++++-------------
 1 file changed, 36 insertions(+), 14 deletions(-)

diff --git a/doc/developer.texi b/doc/developer.texi
index df43119f98..afa0148137 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -274,10 +274,6 @@ symbols. If in doubt, just avoid names starting with @code{_} altogether.
 @section Miscellaneous conventions
 
 @itemize @bullet
- at item
-fprintf and printf are forbidden in libavformat and libavcodec,
-please use av_log() instead.
-
 @item
 Casts should be used only when necessary. Unneeded parentheses
 should also be avoided if they don't make the code easier to understand.
@@ -286,6 +282,42 @@ should also be avoided if they don't make the code easier to understand.
 @anchor{Development Policy}
 @chapter Development Policy
 
+ at section Code behaviour
+
+ at subheading Correctness
+The code must be valid. It must not crash, abort, access invalid pointers, leak
+memory, cause data races or signed integer overflow, or otherwise invoke
+undefined behaviour. Error codes should be checked and, when applicable,
+forwarded to the caller.
+
+ at subheading Thread- and library-safety
+Our libraries may be called by multiple independent callers in the same process.
+These calls may happen from any number of threads and the different call sites
+may not be aware of each other - e.g. a user program may be calling us directly,
+and use one or more libraries that also call us. The code must behave correctly
+under such conditions.
+
+ at subheading Robustness
+The code must treat as untrusted any bytestream received from a caller or read
+from a file, network, etc. It must not misbehave when arbitrary data is sent to
+it - typically it should print an error message and return
+ at code{AVERROR_INVALIDDATA} on encountering invalid input data.
+
+ at subheading Memory allocation
+The code must use the @code{av_malloc()} family of functions from
+ at file{libavutil/mem.h} to perform all memory allocation, except in special cases
+(e.g. when interacting with an external library that requires a specific
+allocator to be used).
+
+All allocations should be checked and @code{AVERROR(ENOMEM)} returned on
+failure. A common mistake is that error paths leak memory - make sure that does
+not happen.
+
+ at subheading stdio
+Our libraries must not access the stdio streams stdin/stdout/stderr directly
+(e.g. via @code{printf()} family of functions), as that is not library-safe. For
+logging, use @code{av_log()}.
+
 @section Patches/Committing
 @subheading Licenses for patches must be compatible with FFmpeg.
 Contributions should be licensed under the
@@ -395,11 +427,6 @@ If it is a bug, the bug has to be fixed. If it is not, the code should
 be changed to not generate a warning unless that causes a slowdown
 or obfuscates the code.
 
- at subheading Check untrusted input properly.
-Never write to unallocated memory, never write over the end of arrays,
-always check values read from some untrusted source before using them
-as array index or other risky things.
-
 @section Library public interfaces
 Every library in FFmpeg provides a set of public APIs in its installed headers,
 which are those listed in the variable @code{HEADERS} in that library's
@@ -811,11 +838,6 @@ an explanation why to your patchset, its ok to not test if theres a reason.
 @item
 If you added YASM code please check that things still work with --disable-yasm.
 
- at item
-Make sure you check the return values of function and return appropriate
-error codes. Especially memory allocation functions like @code{av_malloc()}
-are notoriously left unchecked, which is a serious problem.
-
 @item
 Test your code with valgrind and or Address Sanitizer to ensure it's free
 of leaks, out of array accesses, etc.
-- 
2.40.1