Clean code and Innovation versus Backward compatibility, deprecation, etc, was Re: What does deprecated mean? - was: Re: Rename Node2/node2 to Node/node in trunk

[Luciano Resende <lu...@gmail.com>]

Tuscany has been in a "backward compatible" mode at least since
version SCA Java 1.0, and we have been using all kinds of workarounds
(e.g deprecation and whole module copies) to maintain backward
compatibility. The side effect of this is less innovation in the
project, legacy code and possible duplication.

 If we look into Tuscany code today, we see the following modules
having @deprecated code
   - binding-ws, binding-ws-axis2, contribution, core-spi,
core-spring, data-api, databinding-sdo, host-webapp, interface,
interface-java, policy

We also have at least couple obsolete or non-maintained modules still in trunk
   - assembly-java-dsl, binding-feed, xxx-notification, etc

I think we should start some code/module clean-up in our development
stream, and have more flexibility to innovate in the trunk, this could
also be viewed as a preparation for changes from the next release of
the SCA specifications. If we really need to maintain a high level of
backward compatibility, we could probably look into different
alternatives such as having the more stable code as a separate
development stream.


On Thu, Aug 21, 2008 at 4:32 AM, ant elder <an...@apache.org> wrote:
>
>
> On Thu, Aug 21, 2008 at 10:44 AM, Simon Laws <si...@googlemail.com>
> wrote:
>>
>>
>> On Thu, Aug 21, 2008 at 9:42 AM, ant elder <an...@gmail.com> wrote:
>>>
>>>
>>> On Thu, Aug 21, 2008 at 9:11 AM, Simon Laws <si...@googlemail.com>
>>> wrote:
>>>>
>>>>
>>>> On Thu, Aug 21, 2008 at 8:52 AM, haleh mahbod <hm...@gmail.com> wrote:
>>>>>
>>>>> Doesn't deprecation mean the code will be there for a while and
>>>>> therefore the new code will not break existing user code?
>>>>>
>>>>> How long will deprecated code stay around in Tuscany? It would be good
>>>>> to establish a guideline so users can plan to move to the new code.
>>>>>
>>>>> Can there be a log of deprecated APIs under documentation page or
>>>>> download page? This will help users to better plan for moving code to the
>>>>> new APIs/SPIs.
>>>>
>>>>
>>>>>
>>>>>
>>>>
>>>> snip...
>>>>
>>>> How about...
>>>>
>>>> deprecated = the feature will remain in the code base for at least the
>>>> next 2 releases at the 1.X level. During this time it won't be maintained
>>>> and users are encouraged to move away from it. After this time it is a
>>>> candidate for removal.
>>>>
>>>> Thoughts?
>>>>
>>>> Simon
>>>>
>>>>
>>>
>>> I think its likely to depend on the circumstances and could be different
>>> for different types of changes. Its possible it could be fine in some
>>> circumstances to remove a deprecated feature after just one release, for
>>> some of the less important functions it may even be reasonable to remove
>>> function without deprecation and just document the change in the release
>>> notes. It is also to some degree time dependent as well as release dependent
>>> and if we get several releases out over few months it could be better to not
>>> remove a deprecated feature just because the set number of releases has
>>> past. What i think is important is to consider the impact to users of
>>> changes, so when it does seem like there could be significant user impact
>>> then be more conservative, and vice versa.
>>
>> I agree that it's a matter of circumstance but we should set some
>> expectation. Having a variable approach will be hard to follow. I don't
>> really object to keeping deprecated interfaces in the code base longer than
>> we expected to keep them. Removing interfaces or changing the semantics with
>> little warning will, I think, cause problems though.
>>
>>>
>>>
>>> As it could be hard to come up with a firm policy or guideline how about
>>> saying changes that seem like they might impact backward compatibility
>>> require at least lazy consensus, so post to the ML and wait at least 72
>>> hours before making the change?
>>
>> So this is a different but very good question. How do we judge whether a
>> change is likely to affect backward compatibility? We have to look for red
>> flags such as; does the change require changes to unit tests, itests or
>> samples?. Given that we have some warning that a change is planned we can
>> decide the best approach re. deprecation and migration.
>>
>>
>
> Another aspect to this is what is considered the official backward
> compatible set of features? We don't really have a clearly document set of
> APIs/SPIs or list of stable modules, and we have experimental work that goes
> on in trunk which sometimes does get into releases but is considered alpha
> code to get community feedback. Should we try to come up with this doc?
>
> One thing we could do is create an SCA community test suite like we have for
> SDO, perhaps seeded from the existing itests and vtests but out of the
> java/sca SVN tree so its hard to update without thinking. It could also do
> things like include a copy of some of the extensions code to test the SPI
> backward compatability, and have http unit type testing to test things like
> web integration which doesn't normally get tested unless we manually run the
> samples. Running that suite on each significant change or release we do
> should help hightlight any backward compatibility issues.
>
>    ...ant
>
>
>



-- 
Luciano Resende
Apache Tuscany Committer
http://people.apache.org/~lresende
http://lresende.blogspot.com/

Re: Clean code and Innovation versus Backward compatibility, deprecation, etc, was Re: What does deprecated mean? - was: Re: Rename Node2/node2 to Node/node in trunk

[ant elder <an...@apache.org>]

On Tue, Aug 26, 2008 at 2:52 PM, Simon Laws <si...@googlemail.com>wrote:

<snip>


> I think we do need to maintain a high level of backward compatibility. I
> would go further and say that we need to start testing for it, e.g run our
> trunk test suite(s?) against old Tuscany versions and be able to justify any
> discrepancies.
>
>
+1 to start trying to test for backward compatibility. How about to start
with something like the CTS tests for SCA as suggested over on
http://apache.markmail.org/message/355aeey3gfy7jzrk? I'd help with this but
i think we need some consensus that we should be doing this before going
ahead, what do others think?

   ...ant

Re: Clean code and Innovation versus Backward compatibility, deprecation, etc, was Re: What does deprecated mean? - was: Re: Rename Node2/node2 to Node/node in trunk

[Simon Laws <si...@googlemail.com>]

On Tue, Aug 26, 2008 at 2:03 PM, ant elder <an...@gmail.com> wrote:

> I'm not sure i've seen many serious issues or problems with keeping the old
> code about to maintain backward compatibility so far, but if new function
> really is becoming hard to add and innovation is being hindered then sure
> lets look at some clean up. What i think would help decide this is some
> specific examples -  "i want to do x but can't because of all that old code"
> - type of thing, if we can get a few of those then it would help convince
> everyone that it really is time for a clean up and breaking backward
> compatibility of the trunk.
>
>    ...ant
>
>
> On Thu, Aug 21, 2008 at 11:39 PM, Luciano Resende <lu...@gmail.com>wrote:
>
>> Tuscany has been in a "backward compatible" mode at least since
>> version SCA Java 1.0, and we have been using all kinds of workarounds
>> (e.g deprecation and whole module copies) to maintain backward
>> compatibility. The side effect of this is less innovation in the
>> project, legacy code and possible duplication.
>>
>>  If we look into Tuscany code today, we see the following modules
>> having @deprecated code
>>   - binding-ws, binding-ws-axis2, contribution, core-spi,
>> core-spring, data-api, databinding-sdo, host-webapp, interface,
>> interface-java, policy
>>
>> We also have at least couple obsolete or non-maintained modules still in
>> trunk
>>   - assembly-java-dsl, binding-feed, xxx-notification, etc
>>
>> I think we should start some code/module clean-up in our development
>> stream, and have more flexibility to innovate in the trunk, this could
>> also be viewed as a preparation for changes from the next release of
>> the SCA specifications. If we really need to maintain a high level of
>> backward compatibility, we could probably look into different
>> alternatives such as having the more stable code as a separate
>> development stream.
>>
>>
>> On Thu, Aug 21, 2008 at 4:32 AM, ant elder <an...@apache.org> wrote:
>> >
>> >
>> > On Thu, Aug 21, 2008 at 10:44 AM, Simon Laws <simonslaws@googlemail.com
>> >
>> > wrote:
>> >>
>> >>
>> >> On Thu, Aug 21, 2008 at 9:42 AM, ant elder <an...@gmail.com>
>> wrote:
>> >>>
>> >>>
>> >>> On Thu, Aug 21, 2008 at 9:11 AM, Simon Laws <
>> simonslaws@googlemail.com>
>> >>> wrote:
>> >>>>
>> >>>>
>> >>>> On Thu, Aug 21, 2008 at 8:52 AM, haleh mahbod <hm...@gmail.com>
>> wrote:
>> >>>>>
>> >>>>> Doesn't deprecation mean the code will be there for a while and
>> >>>>> therefore the new code will not break existing user code?
>> >>>>>
>> >>>>> How long will deprecated code stay around in Tuscany? It would be
>> good
>> >>>>> to establish a guideline so users can plan to move to the new code.
>> >>>>>
>> >>>>> Can there be a log of deprecated APIs under documentation page or
>> >>>>> download page? This will help users to better plan for moving code
>> to the
>> >>>>> new APIs/SPIs.
>> >>>>
>> >>>>
>> >>>>>
>> >>>>>
>> >>>>
>> >>>> snip...
>> >>>>
>> >>>> How about...
>> >>>>
>> >>>> deprecated = the feature will remain in the code base for at least
>> the
>> >>>> next 2 releases at the 1.X level. During this time it won't be
>> maintained
>> >>>> and users are encouraged to move away from it. After this time it is
>> a
>> >>>> candidate for removal.
>> >>>>
>> >>>> Thoughts?
>> >>>>
>> >>>> Simon
>> >>>>
>> >>>>
>> >>>
>> >>> I think its likely to depend on the circumstances and could be
>> different
>> >>> for different types of changes. Its possible it could be fine in some
>> >>> circumstances to remove a deprecated feature after just one release,
>> for
>> >>> some of the less important functions it may even be reasonable to
>> remove
>> >>> function without deprecation and just document the change in the
>> release
>> >>> notes. It is also to some degree time dependent as well as release
>> dependent
>> >>> and if we get several releases out over few months it could be better
>> to not
>> >>> remove a deprecated feature just because the set number of releases
>> has
>> >>> past. What i think is important is to consider the impact to users of
>> >>> changes, so when it does seem like there could be significant user
>> impact
>> >>> then be more conservative, and vice versa.
>> >>
>> >> I agree that it's a matter of circumstance but we should set some
>> >> expectation. Having a variable approach will be hard to follow. I don't
>> >> really object to keeping deprecated interfaces in the code base longer
>> than
>> >> we expected to keep them. Removing interfaces or changing the semantics
>> with
>> >> little warning will, I think, cause problems though.
>> >>
>> >>>
>> >>>
>> >>> As it could be hard to come up with a firm policy or guideline how
>> about
>> >>> saying changes that seem like they might impact backward compatibility
>> >>> require at least lazy consensus, so post to the ML and wait at least
>> 72
>> >>> hours before making the change?
>> >>
>> >> So this is a different but very good question. How do we judge whether
>> a
>> >> change is likely to affect backward compatibility? We have to look for
>> red
>> >> flags such as; does the change require changes to unit tests, itests or
>> >> samples?. Given that we have some warning that a change is planned we
>> can
>> >> decide the best approach re. deprecation and migration.
>> >>
>> >>
>> >
>> > Another aspect to this is what is considered the official backward
>> > compatible set of features? We don't really have a clearly document set
>> of
>> > APIs/SPIs or list of stable modules, and we have experimental work that
>> goes
>> > on in trunk which sometimes does get into releases but is considered
>> alpha
>> > code to get community feedback. Should we try to come up with this doc?
>> >
>> > One thing we could do is create an SCA community test suite like we have
>> for
>> > SDO, perhaps seeded from the existing itests and vtests but out of the
>> > java/sca SVN tree so its hard to update without thinking. It could also
>> do
>> > things like include a copy of some of the extensions code to test the
>> SPI
>> > backward compatability, and have http unit type testing to test things
>> like
>> > web integration which doesn't normally get tested unless we manually run
>> the
>> > samples. Running that suite on each significant change or release we do
>> > should help hightlight any backward compatibility issues.
>> >
>> >    ...ant
>> >
>> >
>> >
>>
>>
>>
>> --
>> Luciano Resende
>> Apache Tuscany Committer
>> http://people.apache.org/~lresende <http://people.apache.org/%7Elresende>
>> http://lresende.blogspot.com/
>>
>
>
I think we do need to maintain a high level of backward compatibility. I
would go further and say that we need to start testing for it, e.g run our
trunk test suite(s?) against old Tuscany versions and be able to justify any
discrepancies.

A specific issue I see now is that when we release there are a number of
modules that we exclude and it is not obvious by looking at svn which
modules are considered as part of the distribution and which are not. We
could instigate an sca/modules-dev (or similar) directory to hold those
modules that are not part of the distribution. New modules that are not part
of distribution can be the subject of as much innovation as we care to throw
at them. More care should be taken with modules that are part of the
distribution. There would also be an very explicit decision to move a model
for distribution rather than leaving it to the release manager to filter out
modules.

If we really do get to the stage that progress can't be made without
breaking backward compatibility, for example, when we want to implement
incompatible OASIS features, then we need to branch the code base in some
way that allows us to maintain both new and old versions. I would be nervous
about stopping development completely on the current code base when we do
start to do incompatible changes. Alternatives to assigning the current sca
trunk to incompatible development could be
  - Leveraging the plugability of the runtime by, for example, creating new
model or extension plugins that can be swapped in with new features
  - creating a new project with its own trunk for the next version of
Tuscany so that it is clear that development is likely in both places.

Simon

Re: Clean code and Innovation versus Backward compatibility, deprecation, etc, was Re: What does deprecated mean? - was: Re: Rename Node2/node2 to Node/node in trunk

[ant elder <an...@gmail.com>]

I'm not sure i've seen many serious issues or problems with keeping the old
code about to maintain backward compatibility so far, but if new function
really is becoming hard to add and innovation is being hindered then sure
lets look at some clean up. What i think would help decide this is some
specific examples -  "i want to do x but can't because of all that old code"
- type of thing, if we can get a few of those then it would help convince
everyone that it really is time for a clean up and breaking backward
compatibility of the trunk.

   ...ant

On Thu, Aug 21, 2008 at 11:39 PM, Luciano Resende <lu...@gmail.com>wrote:

> Tuscany has been in a "backward compatible" mode at least since
> version SCA Java 1.0, and we have been using all kinds of workarounds
> (e.g deprecation and whole module copies) to maintain backward
> compatibility. The side effect of this is less innovation in the
> project, legacy code and possible duplication.
>
>  If we look into Tuscany code today, we see the following modules
> having @deprecated code
>   - binding-ws, binding-ws-axis2, contribution, core-spi,
> core-spring, data-api, databinding-sdo, host-webapp, interface,
> interface-java, policy
>
> We also have at least couple obsolete or non-maintained modules still in
> trunk
>   - assembly-java-dsl, binding-feed, xxx-notification, etc
>
> I think we should start some code/module clean-up in our development
> stream, and have more flexibility to innovate in the trunk, this could
> also be viewed as a preparation for changes from the next release of
> the SCA specifications. If we really need to maintain a high level of
> backward compatibility, we could probably look into different
> alternatives such as having the more stable code as a separate
> development stream.
>
>
> On Thu, Aug 21, 2008 at 4:32 AM, ant elder <an...@apache.org> wrote:
> >
> >
> > On Thu, Aug 21, 2008 at 10:44 AM, Simon Laws <si...@googlemail.com>
> > wrote:
> >>
> >>
> >> On Thu, Aug 21, 2008 at 9:42 AM, ant elder <an...@gmail.com> wrote:
> >>>
> >>>
> >>> On Thu, Aug 21, 2008 at 9:11 AM, Simon Laws <simonslaws@googlemail.com
> >
> >>> wrote:
> >>>>
> >>>>
> >>>> On Thu, Aug 21, 2008 at 8:52 AM, haleh mahbod <hm...@gmail.com>
> wrote:
> >>>>>
> >>>>> Doesn't deprecation mean the code will be there for a while and
> >>>>> therefore the new code will not break existing user code?
> >>>>>
> >>>>> How long will deprecated code stay around in Tuscany? It would be
> good
> >>>>> to establish a guideline so users can plan to move to the new code.
> >>>>>
> >>>>> Can there be a log of deprecated APIs under documentation page or
> >>>>> download page? This will help users to better plan for moving code to
> the
> >>>>> new APIs/SPIs.
> >>>>
> >>>>
> >>>>>
> >>>>>
> >>>>
> >>>> snip...
> >>>>
> >>>> How about...
> >>>>
> >>>> deprecated = the feature will remain in the code base for at least the
> >>>> next 2 releases at the 1.X level. During this time it won't be
> maintained
> >>>> and users are encouraged to move away from it. After this time it is a
> >>>> candidate for removal.
> >>>>
> >>>> Thoughts?
> >>>>
> >>>> Simon
> >>>>
> >>>>
> >>>
> >>> I think its likely to depend on the circumstances and could be
> different
> >>> for different types of changes. Its possible it could be fine in some
> >>> circumstances to remove a deprecated feature after just one release,
> for
> >>> some of the less important functions it may even be reasonable to
> remove
> >>> function without deprecation and just document the change in the
> release
> >>> notes. It is also to some degree time dependent as well as release
> dependent
> >>> and if we get several releases out over few months it could be better
> to not
> >>> remove a deprecated feature just because the set number of releases has
> >>> past. What i think is important is to consider the impact to users of
> >>> changes, so when it does seem like there could be significant user
> impact
> >>> then be more conservative, and vice versa.
> >>
> >> I agree that it's a matter of circumstance but we should set some
> >> expectation. Having a variable approach will be hard to follow. I don't
> >> really object to keeping deprecated interfaces in the code base longer
> than
> >> we expected to keep them. Removing interfaces or changing the semantics
> with
> >> little warning will, I think, cause problems though.
> >>
> >>>
> >>>
> >>> As it could be hard to come up with a firm policy or guideline how
> about
> >>> saying changes that seem like they might impact backward compatibility
> >>> require at least lazy consensus, so post to the ML and wait at least 72
> >>> hours before making the change?
> >>
> >> So this is a different but very good question. How do we judge whether a
> >> change is likely to affect backward compatibility? We have to look for
> red
> >> flags such as; does the change require changes to unit tests, itests or
> >> samples?. Given that we have some warning that a change is planned we
> can
> >> decide the best approach re. deprecation and migration.
> >>
> >>
> >
> > Another aspect to this is what is considered the official backward
> > compatible set of features? We don't really have a clearly document set
> of
> > APIs/SPIs or list of stable modules, and we have experimental work that
> goes
> > on in trunk which sometimes does get into releases but is considered
> alpha
> > code to get community feedback. Should we try to come up with this doc?
> >
> > One thing we could do is create an SCA community test suite like we have
> for
> > SDO, perhaps seeded from the existing itests and vtests but out of the
> > java/sca SVN tree so its hard to update without thinking. It could also
> do
> > things like include a copy of some of the extensions code to test the SPI
> > backward compatability, and have http unit type testing to test things
> like
> > web integration which doesn't normally get tested unless we manually run
> the
> > samples. Running that suite on each significant change or release we do
> > should help hightlight any backward compatibility issues.
> >
> >    ...ant
> >
> >
> >
>
>
>
> --
> Luciano Resende
> Apache Tuscany Committer
> http://people.apache.org/~lresende <http://people.apache.org/%7Elresende>
> http://lresende.blogspot.com/
>