[Xapian-discuss] Deprecation policy question

[Jean-Francois Dockes]

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