Sunday, August 23, 2009

Let's write some deprecation policies

Sebastian writes about version numbers and backwards compatibility and asks:

Should a project have deprecation policies as soon as it hits CPAN with a development release?

I think the answer should be yes - there should always be a deprecation policy. But this deprecation policy does not need to be the full monty of always keeping the backcompat to at least one major version, using strict deprecation cycles etc - it just needs to be stated explicitely and not relying on the version numbering convention as they are not really universal. There is no negative side to putting a few sentences into the docs, only a bit work to formulate them. And here is my idea:

Let's write some deprecation policies

Let's have a list of well formulated policies covering as much as we can of possible circumstances (from experimental to mature, and from one-person projects to team work) that could be copied to the CPAN distribution docs with minimal effort. For the start - here are some ideas:

  • Experimental - no policies at all, use at your own risk
  • Experimental with mailing list announcements of new versions and promise to take into account problems encountered by people testing the new code
  • Backcompat to one version, with a specific minimal time between versions
  • Backcompat to one major version, with a specific minimal time between major releases

In related news mst gives an overview of techniques that can be used for maintaining back-compat - sometimes these are really simple things.


Kartik said...

This is a great idea. I am looking to depreciated some older sdl perl functions. But I have no clue how to do this.

AdamKennedy said...

I'd prefer to see version-explicit backcompatibility.

One (hacky) mechanism I've used in the past goes like this.

our $VERSION = '1.23';
our $BACKCOMPATIBLE = '0.47';

zby said...

@Adam - this sounds like a good idea - always more explicite information is good. But I think that the main purpose of policies is not informing (about what is the oldest version compatible with the current one) - but rather promising to follow a specific procedure when makig an icompatible change to give people time to adjust their code bases.