buildr-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Assaf Arkin" <>
Subject Changes and backward compatibility
Date Tue, 09 Sep 2008 03:28:08 GMT
Every release we make is an opportunity to fix all the reported issues
and bugs.  And to break things that worked before.  Sometimes both at
the same time, which to enough people translate into "nothing worth
upgrading for".

We need to be careful with what we change, how we change, and how we
roll out those changes.  Especially changes that "remove" features,
whether by changing an API, behavior or simply breaking something that
worked before.

I'd like to propose the following policy:

1. Concentrate major changes along minor/major version boundaries, not
point releases (i.e. 1.3, 1.4, 1.5, 2.0, etc).

2. Maintain backward compatibility for at least one minor version.
For example, if we decide to remove a feature and the current release
is 1.3.4, we retain that feature for one minor version (1.4.x) up
until the 1.5.0 release.

3. Provide deprecated warnings in documentation, API and when running
code. The warning should indicate what alternative exists, e.g.
"Please replace with using(:foo=>true)".

4. Maintain specs/tests for both new and deprecated behavior, until
deprecated behavior has been removed.

5. Obviously there will be exceptions to this rule, but having a rule
we can at least minimize/contain these exceptions and know how to deal
with them.


View raw message