[FFmpeg-devel] [RFC] Need an additional maintainer rule when deprecating functions

[Stefano Sabatini]

On date Thursday 2010-11-04 18:15:49 +0100, Cyril Russo encoded:
> 
> Le 04/11/2010 17:14, Anton Khirnov a ?crit :
> >On Thu, Nov 04, 2010 at 04:42:02PM +0100, Cyril Russo wrote:
> >>Hi all,
> >>
> >>   I would like to know if it's possible for those pushing
> >>"attribute_deprecated" patch to be force to document the reason of
> >>the change and mainly, what is the "new" way of doing the same thing
> >>as the previous version.
> >>
> >You're misunderstanding, that patch didn't deprecate anything. It simply
> >marked the stuff that _was already_ deprecated, to make transition to
> >new APIs easier.
> >
> Yes, I'm speaking of the addition of attribute_deprecated that's
> quite recent (one or two week old at worst) and that does *add * a
> warning on the user code.
> You are right that probably, from FFmpeg developer's point of view,
> some API are deprecated since a while, but from a user point of
> view, it's only when GCC says it, that we will consider it. And
> believe me, I'm not like 90% of devs that'll even wait until it's
> *actually removed* to react.
> 
> The point is that you now get a warning that says:
> myfile.c:126: warning: ?something? is deprecated (declared at go_here.h:123)
> 
> And, logically, I'll go to "go_here.h" file at line 123, and try to
> figure out what is the good way to update my code.
> Currently, there is no pointer whatsoever here (go_here.h:123), and
> that's the point of the discussion, that is, FORCE people to had a
> meaningful comment above like:
> go_here.h
> 122 /* @deprecated Please use the function XYZ instead */
> 123 attribute_deprecated int something();
> 
> Or, at least:
> go_here.h
> 122 /* @deprecated This is deprecated because of ... please refer to
> APIChange.txt by 24/09/10 */
> 123 attribute_deprecated int something();

I agree that that deprecation was a little premature, and
documentation should be more complete (especially with regard to the
srcFilter and dstFilter params), anyway if you're already familiar
with the FFmpeg API ist use should be quite obvious (also as you're a
developer so you can read the source and patches are welcome).

Also we're having some issues into updating the API, indeed the FFmpeg
code is still using the old API, so it will take some more time before
it will be actually dropped, but I'm slightly against to remove the
deprecation warning.
-- 
FFmpeg = Fundamentalist and Freak Mere Peaceful Eccentric Goblin