Olly and I have been discussing details of our policy for deprecating features, and we thought it would be useful to canvas users opinions on a particular aspect. From time to time, we remove features from the library (usually because we have a better replacement). To make life easier for users, we've been following a deprecation policy, so that users are given plenty of warning of features which are about to be removed, and are given suggestions of how to change their code. This policy states that (whenever possible) when a feature is marked as deprecated at a particular release of Xapian, the feature will continue to be present and unchanged for a full release cycle. For example, if a feature is deprecated in version 1.0.3, it will remain usable in Xapian throughout the 1.0.x and 1.1.x release series, and finally be removed in release 1.2.0. There are several ways in which a feature is advertised as deprecated: 1. The deprecation is listed in the NEWS file at the time it is first marked as deprecated (ie, in version 1.0.3 in the earlier example). 2. The deprecation is described in documentation comments in the API, with a special marker, so that the list of current deprecations appears in the API documentation (at http://www.xapian.org/docs/apidoc/html/deprecated.html) 3. The deprecation is listed in a table of all current and past deprecations in docs/deprecation.rst, which produces the HTML version http://www.xapian.org/docs/deprecation.html 4. A macro is used to mark features as deprecated, so that compilers will emit a warning when the deprecated feature is used. The point which we wish to canvas opinion on is this final one. The question is whether we should add the macro to features at the time we initially mark them as deprecated, or should wait until the next release series. The advantage of adding the macro immediately is that users get as much warning as possible - but the disadvantage is that code which compiled fine at the start of a release series suddenly starts producing warnings (and indeed, fails to compile if -Werror is being used). There are actually 3 options: 1. Always add the deprecation macro as soon as the feature is deprecated (so, at version 1.0.3 in the above example). This is good because users get as much warning as possible about changes they will need to make to their code, but bad because it will sometimes mean that it is not possible to write code which compiles without warnings with all revisions of xapian within a release series. 2. Always wait until the next release series to add the deprecation macro (so, at version 1.1.0 in the above example). This is good because code which compiled without warnings at a x.y.0 release will continue to compile without warnings for the rest of that release series, but does delay the compiler warning about changes needed to code. 3. Add the deprecation macro if and only if there is an alternative which works with the most recent x.y.0 release. If there is, users can change their code such that it compiles with all releases of Xapian within a given release series without warnings, but not all code which compiles at x.y.0 will continue to compile without warnings. Which of these options seem most helpful to you? -- Richard
On Mon, Sep 24, 2007 at 09:05:36AM +0100, Richard Boulton wrote:> 1. Always add the deprecation macro as soon as the feature is deprecated > (so, at version 1.0.3 in the above example). This is good because users > get as much warning as possible about changes they will need to make to > their code, but bad because it will sometimes mean that it is not > possible to write code which compiles without warnings with all > revisions of xapian within a release series.I see the argument for not wanting to do this because of -Werror. However (and see below for more) I think this is still a better choice than the alternatives.> 2. Always wait until the next release series to add the deprecation > macro (so, at version 1.1.0 in the above example). This is good because > code which compiled without warnings at a x.y.0 release will continue > to compile without warnings for the rest of that release series, but > does delay the compiler warning about changes needed to code.This feels to me to be the most user-focussed way of doing it, HOWEVER it means the macro isn't a true deprecation macro. It's instead a notification of imminent breakage - kind of raising the warning level. For that reason I'd vote for (1). People who are compiling -Werror are *wanting* minor things to stop the system from building (and indeed tend to develop in a different kind of vibe to people who are using default compiler flags and ignoring warnings). They want to raise the warning level. They are generally the sorts of people who want to float on the *front* line of the (released version of the) library, rather than a little behind the wave. While personally I think everyone should compile -Werror, I don't think this will discourage those who want to any more than things like the vile type munging you have to do throughout the STL when writing your own code. I also suspect that the majority (and an increasing number) of users of Xapian won't actually be writing in C++ anyway, so putting deprecation into code as soon as possible helps anyone writing extra library layers, or reasonable-sized applications, to ensure they don't miss anything. That is (again, I suspect) mostly going to be the Xapian developers + under half a dozen others, all of whom are likely to follow things reasonably closely, and would really benefit from this tool to make sure we don't miss deprecated features.> 3. Add the deprecation macro if and only if there is an alternative > which works with the most recent x.y.0 release. If there is, users can > change their code such that it compiles with all releases of Xapian > within a given release series without warnings, but not all code which > compiles at x.y.0 will continue to compile without warnings.This feels wrong to me, mostly because the rule is more complex. Simpler rules are better. Conversely, it sounds wrong to me to introduce that situation in the first place. Do we have an example of a deprecation change introduced within a release series that it's impossible to compile smoothly across? We should be avoiding those situations strenuously IMHO. J -- /--------------------------------------------------------------------------\ James Aylett xapian.org james@tartarus.org uncertaintydivision.org
On 9/24/07, Richard Boulton <richard@lemurconsulting.com> wrote:> ... > The point which we wish to canvas opinion on is this final one. The > question is whether we should add the macro to features at the time we > initially mark them as deprecated, or should wait until the next release > series. The advantage of adding the macro immediately is that users get > as much warning as possible - but the disadvantage is that code which > compiled fine at the start of a release series suddenly starts producing > warnings (and indeed, fails to compile if -Werror is being used). > > There are actually 3 options: > > 1. Always add the deprecation macro as soon as the feature is deprecated > (so, at version 1.0.3 in the above example). This is good because users > get as much warning as possible about changes they will need to make to > their code, but bad because it will sometimes mean that it is not > possible to write code which compiles without warnings with all > revisions of xapian within a release series. >I vote for option 1. Fabrice
On Mon, Sep 24, 2007 at 09:05:36AM +0100, Richard Boulton wrote:> 4. A macro is used to mark features as deprecated, so that compilers > will emit a warning when the deprecated feature is used.It's perhaps worth mentioning that this macro requires explicit support from the compiler - currently it works for GCC 3.1 or later, and MSVC 7.0 or later (which I suspect is the majority of users). If you know how to do this for another compiler, do let us know.> 1. Always add the deprecation macro as soon as the feature is deprecated > (so, at version 1.0.3 in the above example). This is good because users > get as much warning as possible about changes they will need to make to > their code, but bad because it will sometimes mean that it is not > possible to write code which compiles without warnings with all > revisions of xapian within a release series.It's always possible to write code using the preprocessor, like this: #if XAPIAN_MAJOR_VERSION == 1 && XAPIAN_MINOR_VERSION < 3 old_way(); #else new_way(); #endif This approach could get ugly for some cases, though probably not for the sort of changes we're likely to be happy to include in a point release. It's also worth noting that you can easily disable all Xapian deprecation warnings like the bindings do: #define XAPIAN_DEPRECATED(D) D That's not a documented feature, but we could document it, or perhaps better provide a "XAPIAN_NO_DEPRECATED_WARNINGS" macro the user can define which does this internally (in case we find we need to change how that macro works). I think ideally we want the policy which API users find most useful, but if different people want different things, then this is one solution. Cheers, Olly
Richard Boulton writes: > Olly and I have been discussing details of our policy for deprecating > features, and we thought it would be useful to canvas users opinions on > a particular aspect. > ... > 4. A macro is used to mark features as deprecated, so that compilers > will emit a warning when the deprecated feature is used. > > ... > There are actually 3 options: > 1. Always add the deprecation macro as soon as the feature is deprecated > ... > 2. Always wait until the next release series to add the deprecation > macro (so, at version 1.1.0 in the above example). > ... > 3. Add the deprecation macro if and only if there is an alternative > which works with the most recent x.y.0 release. I am in favor of option 2. I think that the implicit assumption for revision changes is that they are safe to follow, users should not have to think about them (accidents may happen of course). For a revision (smallest published change) change, the developpers are stating that the new software works just the same, and that users can follow blindly and will not have any adjustments to perform. This does not preclude new features, if things stay 100% compatible and full confidence is obtained that no new defects were introduced (a difficult thing). If this contract is not respected, the distinction between revision and minor release becomes less useful, it's a question of confidence. If you add the macro on a revision change, the compilation will fail for people who use -Werror (not my case by the way). Contract broken. By adding the warning on the minor release change, people still have a full release cycle to adapt, and nothing unexpected happens if things break (things *are* expected to break on release changes). It just feels cleaner to me this way, but take it lightly: I do understand that we didn't sign any contract :) , and I don't feel extremely strongly either way. jf
[Bringing this back onto the list so others can see.] Jean-Francois Dockes wrote:> Richard Boulton writes: > > Of course, we could just specify that the "contract" is that we'll not > > break compilation as long as you either don't specify -Werror, or > > specify -Wno-deprecated. > > > > What I'm really wondering is how many (if any) xapian users actually > > compile with -Werror, and would thus end up with broken builds in this > > case. And also, whether such users are compiling this way because they > > want to get the latest warnings, and would appreciate their build > > breaking in this situation. > > Obviously, you are free to specify things the way you like :) Does the > Xapian web site have an explicit description of how the version numbers are > used ?Not really - there is a section in http://www.xapian.org/docs/deprecation.html about the compatibilty "guarantees" we try and provide, but it doesn't discuss things like the difference between a major and a minor release.> As a user, I find it useful if packages have a clear separation of what the > numbers mean, so that they can be a bit more useful: > > - Smallest level: no voluntary disruption expected for any reasonable use > of the software (using -Werror falls inside "reasonable" in my view). > > - Next level: minor disruption possible.>> - Next: serious disruption expected. > > (The "voluntary" at the first level is there because serious trouble, like > a reindex, could be forced by an unavoidable bug fix, but the cause is the > bug, not the revision here).A sensible distinction.> My preferred solution would actually be that you bump the middle number > whenever you feel like adding the warning. So the -Werror people have their > breakage and I have my numbers :)That might be a plausible system in future. I can certainly see merit in it. -- Richard