From 40020e171a3549a2c0b65ce6f2649aec868872f2 Mon Sep 17 00:00:00 2001 From: Anton Khirnov Date: Wed, 11 Apr 2012 15:45:22 +0200 Subject: [PATCH] doxy: add a section about versioning. --- libavutil/avutil.h | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/libavutil/avutil.h b/libavutil/avutil.h index 5ed33a9777..ddb34a1dda 100644 --- a/libavutil/avutil.h +++ b/libavutil/avutil.h @@ -41,6 +41,39 @@ * @li @ref lavu "libavutil" common utility library * @li @ref lavr "libavresample" audio resampling, format conversion and mixing * @li @subpage libswscale color conversion and scaling library + * + * @section libav_versioning Versioning and compatibility + * + * Each of the Libav libraries contains a version.h header, which defines a + * major, minor and micro version number with the + * LIBRARYNAME_VERSION_{MAJOR,MINOR,MICRO} macros. The major version + * number is incremented with backward incompatible changes - e.g. removing + * parts of the public API, reordering public struct members, etc. The minor + * version number is incremented for backward compatible API changes or major + * new features - e.g. adding a new public function or a new decoder. The micro + * version number is incremented for smaller changes that a calling program + * might still want to check for - e.g. changing behavior in a previously + * unspecified situation. + * + * Libav guarantees backward API and ABI compatibility for each library as long + * as its major version number is unchanged. This means that no public symbols + * will be removed or renamed. Types and names of the public struct members and + * values of public macros and enums will remain the same (unless they were + * explicitly declared as not part of the public API). Documented behavior will + * not change. + * + * In other words, any correct program that works with a given Libav snapshot + * should work just as well without any changes with any later snapshot with the + * same major versions. This applies to both rebuilding the program against new + * Libav versions or to replacing the dynamic Libav libraries that a program + * links against. + * + * However, new public symbols may be added and new members may be appended to + * public structs whose size is not part of public ABI (most public structs in + * Libav). New macros and enum values may be added. Behavior in undocumented + * situations may change slightly (and be documented). All those are accompanied + * by an entry in doc/APIchanges and incrementing either the minor or micro + * version number. */ /**