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

[Clément Bœsch]

On Fri, Aug 11, 2017 at 11:12:32AM +0200, Nicolas George wrote:
> 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.
> 

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".

> > 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?

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).

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

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.

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

I consider that one a long standing and deeper issue we haven't solved
yet. 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.

> 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.

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.

> This patch is not changing the policy, it is documenting 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?

-- 
Clément B.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 488 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20170811/8519fbb4/attachment.sig>