Backwards Compatibility
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. Maintain that expectation in the spec, for example:
it 'should do a deprecated behavior' do Buildr.VERSION.should < '1.5' ... end
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.