hc-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From James Abley <james.ab...@gmail.com>
Subject Re: [DISCUSS] Deprecated code policy
Date Fri, 23 Nov 2012 08:18:12 GMT
I don't know if you can use semantic versioning [1], or if apache projects
have a different way of defining major / minor / point version changes?

[1] http://semver.org/


On 23 November 2012 00:00, sebb <sebbaz@gmail.com> wrote:

> On 22 November 2012 22:16, Oleg Kalnichevski <olegk@apache.org> wrote:
> > On Thu, 2012-11-22 at 18:40 +0000, sebb wrote:
> >> On 22 November 2012 18:03, Gary Gregory <garydgregory@gmail.com> wrote:
> >> > 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.
> >>
> >> HC4 is a completely different product from HC3, whereas what we are
> >> discussing now is a gradual evolution.
> >>
> >> > 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.
> >>
> >> Co-location - i.e. allowing both to play nicely in the same
> >> classloader - is only necessary if there are systems that *need* both.
> >>
> >> For example, JMeter uses both HC3 and HC4, but there's no reason for
> >> it to use HC4 and HC4-new together.
> >> JMeter will be amended as necessary to be able to use the updated API.
> >>
> >> > All of this leads me to think that the new HC API should be in a
> version 5
> >> > with a new package name.
> >>
> >> Changing package name (and AID) does guarantee that the different
> >> versions can co-exist.
> >> However it means a lot more changes to source code.
> >>
> >> With gradual introduction and removal of methods it's possible to phase
> updates.
> >> However, if HC5 were to both introduce useful new methods and remove
> >> deprecated ones this would make the update process slightly more
> >> involved.
> >>
> >> > 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.
> >>
> >> As I already wrote, Commons Lang is a very different proposition.
> >> Headaches (jar hell) come from having multiple independent
> >> dependencies on Lang in the same classloader and not being able to
> >> update them all.
> >> If there is only one dependency on Lang, that could be updated without
> problems.
> >>
> >> If there are genuine use cases where multiple independent parts of a
> >> system all depend on HC4, then yes, it might be worth striving for
> >> strict binary compatibility.
> >> But otherwise I think it's probably unnecessary overhead for HC4.
> >>
> >> As to whether the next version should be 4.x or 5.0, I don't
> particularly mind.
> >> A major version bump may make sense at this point.
> >>
> >
> > Co-location is a very valid and relevant subject. It is great that Gary
> > brought it up. Luckily we do not have to make a decision about it as
> > yet. HC 4.3 can be and is planned to be fully backward compatible with
> > 4.2. One should be able to simply drop 4.3 release in place of 4.2 and
> > still have everything working without any modification. The price of
> > such backward compatibility is of course having to keep two or more
> > versions of essentially the same code with some variations and a
> > different class name. The benefit of this approach is that it enables
> > users to migrate more gradually.
>
> It's only possible for a new version to be a drop-in replacement if it
> is binary compatible.
> That implies that methods cannot be deleted. [Unless they are clearly
> not part of the public API]
>
> > I think HC4 is used widely enough to result in situations where multiple
> > sub-components of the same system depend on different versions of HC4.
> > Spring alone makes such situation very likely.
>
> In which case, HC is much more like Commons than I supposed, and
> option 2 is a non-starter..
>
> > At the same time we have
> > to be realistic about our capacity to maintain deprecated functionality.
> > If we can't do it right (and we cant) we will serve our users better by
> > removing it. I personally think two year / two feature releases is a
> > reasonable time frame to expect people to migrate off deprecated code.
> > We no longer have to maintain strict binary compatibility forever just
> > to please some people at Google. As long as we clearly articulate our
>
> If we wish to support Spring we still have to maintain strict binary
> compatibility within a given package name and associated AID.
>
> > policy in this regard and stick to it we will be acting responsibly
> > enough given the existing project constraints.
>
> The policy also has to be workable within the likely usage scenarios.
>
> For example, for JMeter it would be fine to drop deprecated methods
> after a couple of releases, but AFAICT that is not the case for
> Spring.
> There's no guarantee that all the Spring components can be upgraded
> within a given release time-frame - or indeeed ever -so breaks in
> compatibilty must be accompanied by a change in package name/AID.
>
> > 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
>
>

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