[FFmpeg-devel] [PATCH 01/16] doc/filters: document the unstability of the shorthand options notation.

[Nicolas George]

Le quartidi 24 thermidor, an CCXXV, Clement Boesch a écrit :
> I'm afraid of the situation where a developer will feel like the order of
> the options is not ideal, or an option could be renamed for consistency
> with other filters, and will take the easy way out "oh well, we documented
> it's unstable, users can only blame themselves for relying on it, not even
> mentioning the new order/name is much better for everyone".

In my mind, even with this documentation commit, changing the order of
an option would still require posting a patch on the mailing-list to
discuss it. It could be stated explicitly, but I do not know where (the
user documentation is not the place).

As for renaming options, this is absolutely not allowed.

> If you're referring to this current patch serie, can you list here all the
> filters that are affected by an API break and to what degree?
> 
> We can discuss here if it's an acceptable change or not, and should
> require a compatibility code (maybe it will be for one or two filters
> only).

All the filters that use framesync2.h and have any of the "shortest",
"eof_action" and "repeatlast" options lose the possibility to set these
options by shorthand notation. I.e. you can no longer put 1 in the fifth
or sixth position in the arguments list and hope it will fall on
"shortest".

> We could consider an API to deprecate an AVOption for future similar
> issue. I think we already had such discussion in the past (maybe that was
> around the time we changed "user-agent" into "user_agent"), involving the
> presence of a flag.

Yes, we could, and that takes time that could be dedicated to fixing
actual bugs or implementing new features. Ask any user: "if you agree to
always write x=, y= in your overlay filters, I can fix your bug faster,
what do you prefer?", I know what they will answer.

> I consider that one a long standing and deeper issue we haven't solved
> yet.

Yes, but it still makes my point: the shorthand notation is currently
broken, and we might as well take the benefits from it.

>      My position here is that I do believe all the long-description of
> option belongs in the source code itself (under NULL_IF_CONFIG_SMALL()
> maybe) and the final documentation should be generated from it.
> 
> That way, we won't have to worry about option orders or inconsistencies
> between code and documentation. It will also allow having a cleaner
> documentation wrt option types (mainly thinking about bool values here).
> 
> That's a large project, but I don't think it's hard.

I agree. In fact, a few months ago I posted a detailed plan of an API to
replace the AVOption system that included that and many other things,
including getting rid of escaping hell.

> I think we've been careful about avoiding such mistakes. I have the
> feeling this may only affect options at the end of already long options
> list, so the impact is mitigated.

Yes, but when it comes to trust, it is all or nothing: right now, users
cannot trust the order given in the documentation, and they are not
warned of it.

> And my position is that it's currently not that bad handled and should be
> improved.
> 
> In the past, we've been breaking the C API and ABI several times by
> "mistakes". Our documentation never was perfect either, and still isn't.
> Does that mean we should document that users should never expect any API
> stability from the FFmpeg project because we're just shitty at it?

No, but that means that when a specific has been in fact unstable and
people did not complain about it, we can get rid of it with less hassle.

Regards,

-- 
  Nicolas George