[FFmpeg-devel] [PATCH 3/3] doc/developer.texi: add a section on API/ABI compatibility

[Stefano Sabatini]

On date Wednesday 2023-03-15 15:07:46 +0100, Anton Khirnov wrote:
> Document established practices in it.
> ---
>  doc/developer.texi | 162 ++++++++++++++++++++++++++++++++++++++++-----
>  1 file changed, 146 insertions(+), 16 deletions(-)
> 
> diff --git a/doc/developer.texi b/doc/developer.texi
> index 5e283227be..c625a9feed 100644
> --- a/doc/developer.texi
> +++ b/doc/developer.texi
> @@ -217,6 +217,7 @@ int myfunc(int my_parameter)
>  ...
>  @end example
>  
> + at anchor{Naming conventions}
>  @section Naming conventions
[...]  
> +
> + at anchor{Major version bumps}
> + at subsection Major version bumps
> +A major version bump signifies an API and/or ABI compatibility break. To reduce
> +the negative effects on our callers, who are required to adapt their code,
> +backward-incompatible changes during a major bump should be limited to:
> + at itemize @bullet
> + at item
> +Removing previously deprecated APIs.
> +
> + at item
> +Performing ABI- but not API-breaking changes, like reordering struct contents.
> + at end itemize
> +

This sounds a bit ambiguous. What qualifies "previously deprecated
APIs"? It looks to me that the current practice is to drop deprecated
symbols after 2 major bumps, so that users have the opportunity to
adapt their code depending on the deprecations warnings before the
deprecated symbols are finally removed at the next bump. If that's so,
maybe this can be formalized here.

[...]

LGTM otherwise, thanks.