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 <[email protected]> wrote: > On 22 November 2012 22:16, Oleg Kalnichevski <[email protected]> wrote: > > On Thu, 2012-11-22 at 18:40 +0000, sebb wrote: > >> On 22 November 2012 18:03, Gary Gregory <[email protected]> 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: [email protected] > > For additional commands, e-mail: [email protected] > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > >
