[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'd rather make such changes justified and documented as exceptional in
> the Changelog (or in APIchanges) when we can't get around it cleanly, than
> documenting a free for all area.
> 
> You're saying documenting the risk or potential changes helps us make
> changes more easily with more transparency, but no matter the wording, to
> me it looks like it's going to be a slippery slope where developers
> interpret it differently and will abuse that declared rule whenever
> possible. Indeed, it's the perfect defense against users and other
> developers when breaking the interface.

Can you explain what you mean exactly? I am very doubtful about
"slippery slope" arguments, they usually have at their core the fallacy
of trusting your now-self more than your later-self, while actually your
later-self will have more information and thus be able of better
decisions.

> So yeah, I'm in favor of "no API breakage" (of course, major version bumps
> allow to bypass this), whatever the form, and we can always make
> documented exceptions for obscures options after a discussion.

This would be nice, in principle. But that does not tell me what to do
in practice.

Will you implement and test the compatibility code, soon so that the
patch series can be pushed, fixing the bugs it is fixing and allowing
work to continue?

Will you do that in the future when filters are converted to the new
options system?

Will you go over all the filter's documentation to fix the places where
the order does not match?

The last paragraph is one of my strongest arguments, and nobody
addressed it yet: the shorthand notation is not stable. Right now. We
have on occasion inserted options out of order, and the order is in fact
not documented since the documentation does not match the
implementation. This patch is not changing the policy, it is documenting
it.

Regards,

-- 
  Nicolas George