hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gary Gregory <garydgreg...@gmail.com>
Subject Re: [DISCUSS] Deprecated code policy
Date Thu, 22 Nov 2012 18:03:30 GMT
Hi all,

<ot>
  For US folks out there on the interwebs, Happy Thanksgving day to you
all. In this context, I am thankful for this community of like and
open-minded software gurus, tinkerers, and bit wranglers.
</ot>

I find it helpful to think about this in two parts: process and labeling
(or what version to label code). This is my perfect version world:

Process:

I like to release one version N that includes @[D|d]eprecated code with a
comment that states the EOL policy, e.g. "This class/method will be removed
in version A.B" *AND* the doc MUST contain a pointer to what to do instead.

The simplest process is to deprecate in version N and remove in the next
(major) version N+1, e.g. 4.2 and 5.0.

Labeling:

Strictly, speaking I like API breakage in "major" releases only: 4.0, 5.0,
6.0 and so on. It's just simpler to think about even if it leads to
"version inflation". When I pick up a new major version, I know what I am
in for. In Commons-land, this is also an opportunity to offer co-location
as a feature by renaming the package from o.a.project to o.a.project2,
o.a.project3, and so on. This is what Commons Lang did for version 3. The
POM AID should also be renamed at this time.

I would only deprecate in a minor release (4.3), not a maintenance release
(4.2.3). That's just because I don't expect surprises in maintenance
releases, I expect a maint. release to be used in a drop and go fashion
without deprecated warnings popping up. IOW, no new APIs in a maint release.

HTTP Components

How does this match up with this project? What's a good pragmatic approach?

Well, now is a good time to talk about this since HttpClient will offer a
new API.

Today I can co-locate (I'm not sure what to call this feature) HttpClient 3
and 4 because, this project is now a TLP and has a different package name.

So my first question is: do we want to 'break' co-location for the new
version or keep it? Do we want HC Next to live next to HC 4.2?

The other way to ask this is: why would you not want to co-locate v4 and
vNext.

All of this leads me to think that the new HC API should be in a version 5
with a new package name.

>From experience in a real world app server, I can testified that having
Commons Lang 2 and 3 co-located is a genius feature which has avoid us
countless headaches.

Gobble, Gobble,
Gary


On Thu, Nov 22, 2012 at 9:27 AM, sebb <sebbaz@gmail.com> wrote:

> On 22 November 2012 13:46, Oleg Kalnichevski <olegk@apache.org> wrote:
> > Folks
> >
> > There are lots of changes planned for the 4.3 series that will require
> > many of the old implementation classes to be deprecated in favor of
> > newer ones with a different API. While the amount of deprecated code
> > will be moderate in HttpCore there will be LOTS of it in HttpClient. We
> > should start thinking how we want to go about deprecated code in the 4.x
> > code line.
> >
> > (1) We could keep deprecated functionality indefinitely to maximize
> > compatibility. In this case we should start thinking about 5.0 and API
> > incompatible changes soonish as we have already accumulated quite a lot
> > of deprecated legacy code.
> >
> > (2) Alternatively, we could be selectively removing deprecated code
> > after a certain number of feature releases (two feature releases) and a
> > certain grace period (approximately two years) and keep 5.0 for some
> > really major changes such as HTTP/2.0 or HTTP/1.1bis. By the way, this
> > is what we have done about stuff deprecated in 4.0 GA.
> >
> > I am leaning more towards option 2 and therefore would like to proceed
> > with removal of code deprecated in the 4.1 release from the 4.3 branch
> > (both HttpCore and HttpClient).
> >
> > What are your thoughts? What would be your preference?
>
> Option 2 breaks binary compatibility, so is not suitable for all
> libraries (e.g. it would not be suitable for Commons components, which
> are likely to be referenced multiple times in the same classpath).
>
> However, in the case of HC, it seems very unlikely that a single
> classpath will contain multiple independent dependencies on HC.
>
> So Option 2 seems the best way forward in this case.
>
> > Oleg
> >
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> > For additional commands, e-mail: dev-help@hc.apache.org
> >
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@hc.apache.org
> For additional commands, e-mail: dev-help@hc.apache.org
>
>


-- 
E-Mail: garydgregory@gmail.com | ggregory@apache.org
JUnit in Action, 2nd Ed: <http://goog_1249600977>http://bit.ly/ECvg0
Spring Batch in Action: <http://s.apache.org/HOq>http://bit.ly/bqpbCK
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message