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 _______________________________________________ ffmpeg-devel mailing list ffmpeg-devel@ffmpeg.org http://ffmpeg.org/mailman/listinfo/ffmpeg-devel
