On Sat, Mar 02, 2013 at 06:00:08PM +0100, Reinhard Tartler wrote: > On Sat, Mar 2, 2013 at 5:30 PM, Diego Biurrun <[email protected]> wrote: > > On Sat, Mar 02, 2013 at 05:10:57PM +0100, Reinhard Tartler wrote: > >> On Sat, Mar 2, 2013 at 5:04 PM, Diego Biurrun <[email protected]> wrote: > >> > On Sat, Mar 02, 2013 at 12:46:32PM +0100, Reinhard Tartler wrote: > >> >> > >> >> --- a/doc/developer.texi > >> >> +++ b/doc/developer.texi > >> >> @@ -547,4 +547,107 @@ why the expected result changed. > >> >> +Note that we promise to our users that the resulting shared libraries > >> >> +never break programs that have been @strong{compiled} against previous > >> >> +versions of @strong{Libav} in any case! However, since from time to > >> >> +time we do change APIs in our libraries that may require adaptations to > >> >> +applications, special care must be taken to not break executables that > >> >> +have been compiled against earlier versions of libav. The necessary > >> >> +steps are best discussed on the @strong{libav-devel} mailing list and > >> >> +may involve bumping the major version of the library or adjustments to > >> >> +the symbol versioning file. > >> > > >> > I'm still not too happy with this paragraph. How about something along > >> > the lines of > >> > > >> > Our releases come with certain API and ABI stability guarantees. Point > >> > releases must never break programs compiled against previous versions > >> > of our libraries from the same release branch. > >> > > >> > However, from time to time, we do make API changes that require > >> > adaptation > >> > in applications. Such changes are only allowed in major releases and > >> > will > >> > require further steps such as bumping library version numbers and/or > >> > adjustments to the symbol versioning file. > >> > >> TBH, I fail to see the practical differences between the two wordings. > >> I guess that you fear that someone may misinterpret how we are > >> maintaining API/ABI stability, but I fail to see how your wording > >> addresses this. Just to be safe, can you please elaborate on your > >> concerns? > > > > To me your version sounds as if we did not allow ABI/API changes at > > all, but this is not the case. We do not allow them in point releases, > > in major releases they are allowed if certain issues are considered. > > Well, the difference now becomes pretty petty. You say "we do allow > them if certain things are considered", whereas my wording makes them > more explicit: If applications get broken and we notice, then we need > to something about it.
Your paragraph confused me and I know what it's supposed to say. That's an indication that others might get confused as well. I'm not saying my alternative is perfect, but I do think it moves in the right direction. If you have further improvements, I'm all ears. > > So I split the paragraph in statements about major and point releases, > > which hopefully makes it clearer what stability guarantees apply to > > each type of release. > > Hm. maybe we could add a simple 2x2 table, one one axis the kind of > stability guarantee and on the other axis the release kind? > > I'll think about it. Sounds like a bit of overkill to me; another update to my suggestion should do IMO ... Diego _______________________________________________ libav-devel mailing list [email protected] https://lists.libav.org/mailman/listinfo/libav-devel
