commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mark Thomas <ma...@apache.org>
Subject Re: [DBCP] @since markers for 2.0 release
Date Wed, 26 Feb 2014 14:26:30 GMT
On 26/02/2014 13:46, Matt Benson wrote:
> On Feb 26, 2014 4:35 AM, "Gilles" <gilles@harfang.homelinux.org> wrote:
>>
>> On Wed, 26 Feb 2014 10:30:00 +0000, Mark Thomas wrote:
>>>
>>> I'm wondering what to do about @since markers. As DBCP2 is in a
>>> completely new package, arguably everything is new for this release. The
>>> existing @since markers don't make a lot of sense. Therefore, I am
>>> currently considering removing all @since markers from the code base.
>>> They would then be used from the next release to indicate what had
> changed.
>>>
>>> Thoughts?
>>
>>
>> In Commons Math, we kept the markers referring to the older major
> versions,
>> even though the packages have changed twice already.
>>
> 
> My inclination in general is to follow the example Gilles provides from CM
> unless, for instance, the API has been completely rewritten.

The API hasn't been completely re-written but there have been some
extensive changes. I temporarily changed the package back to dbcp and
ran clirr. It reported 242 errors (and 214 infos). That is a fair amount
of breakage and it varies all the way from a package that has been
entirely removed to a protected field being made final.

And that doesn't include the fields whose meaning has changed between
1.x and 2.x.

I'm still leaning towards removing the @since tags. My main reason for
this is that, if they are left in, users are left with an incomplete
impression of what changed from 1.x to 2.0. I'd much rather start afresh
in 2.0 and use @since to document what has changed from 2.0 onwards.

Mark


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message