You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@buildr.apache.org by Assaf Arkin <ar...@intalio.com> on 2008/09/09 05:28:08 UTC
Changes and backward 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.
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.
Assaf
Re: Changes and backward compatibility
Posted by Assaf Arkin <ar...@intalio.com>.
On Sun, Oct 12, 2008 at 10:22 AM, lacton <la...@users.sourceforge.net> wrote:
> On Wed, Sep 10, 2008 at 6:47 PM, Assaf Arkin <ar...@intalio.com> wrote:
>>>> 4. Maintain specs/tests for both new and deprecated behavior, until
>>>> deprecated behavior has been removed.
>>>
>>> To document this, I suggest we add expectations in our specs.
>>>
>>> E.g.,
>>>
>>> it 'should do a deprecated behavior' do
>>> Buildr.VERSION.should < '1.5'
>>> ...
>>> end
>>>
>>> That way, when we reach version 1.5, we'll know automatically what
>>> needs to be removed. :-)
>>
>> +1 (we should add this to all the 1.2.x deprecated features if we can
>> remember what they are)
>
> I added my first deprecation test at revision 703850 on trunk.
>
> If I get positive feed back on this, I'll keep adding this kind of tests.
+1
>
> Lacton
>
Re: Changes and backward compatibility
Posted by lacton <la...@users.sourceforge.net>.
On Wed, Sep 10, 2008 at 6:47 PM, Assaf Arkin <ar...@intalio.com> wrote:
>>> 4. Maintain specs/tests for both new and deprecated behavior, until
>>> deprecated behavior has been removed.
>>
>> To document this, I suggest we add expectations in our specs.
>>
>> E.g.,
>>
>> it 'should do a deprecated behavior' do
>> Buildr.VERSION.should < '1.5'
>> ...
>> end
>>
>> That way, when we reach version 1.5, we'll know automatically what
>> needs to be removed. :-)
>
> +1 (we should add this to all the 1.2.x deprecated features if we can
> remember what they are)
I added my first deprecation test at revision 703850 on trunk.
If I get positive feed back on this, I'll keep adding this kind of tests.
Lacton
Re: Changes and backward compatibility
Posted by Assaf Arkin <ar...@intalio.com>.
On Tue, Sep 9, 2008 at 11:00 AM, lacton <la...@users.sourceforge.net> wrote:
> On Tue, Sep 9, 2008 at 5:28 AM, Assaf Arkin <ar...@intalio.com> wrote:
>> 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".
>
> I know what you mean. I have this issue with release 1.3.2. It has
> several enhancement I'd like for my day job, but issue BUILDR-106 is a
> blocker, so my team is sticking with 1.3.1.1.
>
>> 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).
>
> I agree with this idea, but I wonder what it means from an SVN point
> of view. When we add a major change, should we do it on trunk? on a
> branch?
(ignoring the SVN vs Git debate)
Does it impact on what currently works? If yes, that means we should
flip the switch to the next minor version number: new functionality,
not necessarily consistent with before; or in reverse, push this until
we make the next major/minor release by doing all that work in a
branch. If it doesn't impact what currently works -- or does that to
fix outstanding bugs -- I say we do it in trunk.
>
>> 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.
>
> Fine with me.
>
>> 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)".
>
> Yes. That's something that's been done quite well in buildr.
>
>> 4. Maintain specs/tests for both new and deprecated behavior, until
>> deprecated behavior has been removed.
>
> To document this, I suggest we add expectations in our specs.
>
> E.g.,
>
> it 'should do a deprecated behavior' do
> Buildr.VERSION.should < '1.5'
> ...
> end
>
> That way, when we reach version 1.5, we'll know automatically what
> needs to be removed. :-)
+1 (we should add this to all the 1.2.x deprecated features if we can
remember what they are)
Assaf
>
>> 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.
>
> +1
>
> Lacton
>
Re: Changes and backward compatibility
Posted by lacton <la...@users.sourceforge.net>.
On Tue, Sep 9, 2008 at 5:28 AM, Assaf Arkin <ar...@intalio.com> wrote:
> 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".
I know what you mean. I have this issue with release 1.3.2. It has
several enhancement I'd like for my day job, but issue BUILDR-106 is a
blocker, so my team is sticking with 1.3.1.1.
> 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).
I agree with this idea, but I wonder what it means from an SVN point
of view. When we add a major change, should we do it on trunk? on a
branch?
> 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.
Fine with me.
> 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)".
Yes. That's something that's been done quite well in buildr.
> 4. Maintain specs/tests for both new and deprecated behavior, until
> deprecated behavior has been removed.
To document this, I suggest we add expectations in our specs.
E.g.,
it 'should do a deprecated behavior' do
Buildr.VERSION.should < '1.5'
...
end
That way, when we reach version 1.5, we'll know automatically what
needs to be 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.
+1
Lacton