[hydra-dev] White paper about interface versioning

[Tilghman Lesher]

On Tuesday 27 April 2010 10:26:33 Leif Madsen wrote:
> ----- Original Message -----
>
> > ----- Original Message -----
> >
> > > It was stated that support would be maintained for as long as the
> > > burden to support such a module did not exceed a threshold. Would it
> > > be wise to specify what such a threshold might be, and how long
> > > ahead of EOL a notice of deprecation would be announced?
> > >
> > > For example, we not give dates as to when Asterisk versions will no
> > > longer be maintained. Perhaps we should do something similar where
> > > we give a minimum date, with the ability to extend support for that
> > > module indefinitely, but always giving a date as to when support
> > > *may* be terminated?
> >
> > If this was done it would have to be at a per-interface level, since
> > that is where versioning occurs. It would also potentially force us to
> > maintain an interface version past the point where the burden becomes
> > immense/insane/nuts.
> >
> > I can certainly see how it would be attractive to third party
> > developers using
> > the interfaces though. With a fixed schedule they could plan
> > accordingly to update
> > their components.
> >
> > My gut feeling says that versioning is going to be a big job no matter
> > what and
> > trying to make it adhere to some form of schedule like above might be
> > pushing it,
> > but I must personally give it more thought.
>
> I can certainly see that, and I guess I'm not specifically saying we should
> have an end-date for every version. Perhaps it can be general like, "will
> support at least 1 year from inception, but after that will no longer be
> supported after 30 days notice".

API versioning can't work the way releases work, though.  The default policy
is that once an API exists, it can never go away.  I would suspect a better
policy would be that a deprecated API will continue to exist for at least N
minor releases, where N > 0, and will go away only if the support burden
becomes too great.  When that happens, the following release will contain
developer notes that specify that the specific versioned API is no longer
available in that release.

Arguments may now commence as to the value of N.

-- 
Tilghman Lesher
Digium, Inc. | Senior Software Developer
twitter: Corydon76 | IRC: Corydon76-dig (Freenode)
Check us out at: www.digium.com & www.asterisk.org