[PROPOSAL] Commons and API change

[Stephen Colebourne <sc...@btopenworld.com>]

Some interesting points have been made so far. I believe I should 
restate my proposal based on feedback (especially as the original was 
written just after a weeks holiday...):

[PROPOSAL]
Whenever a project performs a backwards incompatible API change, two 
things must happen:
a) the major version is increased, eg. from 1.2 to 2.0
b) the package name is changed from o.a.c.foo to o.a.c.foo2, or 
alternatively to a completely new name, eg. o.a.c.bar
[/PROPOSAL]

Thus, this isn't really a JDK5 issue, but a basic issue of dependency 
management. And hence, as poined out, the API version number should be used.

Note however that it is possible to go up a major version without the 
proposed rule being enforced *if* and only if there are no backwards 
incompatible changes (removal of deprecations allowed).

Now, I would suggest that many projects going from a JDK1.2/3/4 base to 
a JDK1.5 base will want to (and should!) make API changes (also, because 
of generics et al its difficult to know if you *have* actually made a 
backwards incompatible change!) As such, I would expect these 1.5 
projects to be subject to the rule in the proposal.

I understand that this is a bit of a pain for end users, but its a pain 
because of the lack of a module system as per JSR277. I would argue that 
changing a package name to migrate is infinitely preferable when dealing 
with a library to coming up against an insoluble jar hell scenario.

Remember, [collections] took one small human error to cause an 
incredible amount of FUD and bad press about commons, that still reduces 
our user-base today. *Every* jar-hell scenario that is created worsens 
this. AFAIK, package renaming is the best, most-viable solution to 
backwards incompatible change in Java today.

Stephen


Henri Yandell wrote:
>> [PROPOSAL]
>> As such, I would like to propose that projects creating a JDK1.5 only
>> release should use a new package name. Thus, in this case, the release
>> would use the package  org.apache.commons.net5.*.
> 
> -1 for a slew of reasons.
> 
> * Lots of source code would have to be touched just to upgrade; big
> pain in the arse for something that is quite likely to not involve any
> other change to a user's source.
> 
> * Building v49 class files is going to explode on a v48 JVM, so people
> are going to be stopped pretty quickly from using the net5 on their
> old JVM. We don't need to protect them via packages.
> 
> * Do we do net3 and net4 if we move from 1.2 to 1.3/1.4? Do we do net6?
> 
>> With this change, a user can have both the old and the new commons-net
>> jars in their classpath without any conflicts.
> 
> Only a JDK 1.5 user (1.6 too I guess). Presuming we make 1.5 targetted
> builds and not 1.2->1.4. And then it's nothing to do with 1.4/1.5 and
> just the classic problem of package clash within dependencies.
> 
>> Note that these users may be different OSS projects, which may upgrade 
>> at different times.
>>
>> Users wishing to migrate from one version to another can simply do a
>> global search and replace on the package name.
>>
>> We must not underestimate the significance of the low-level position of
>> commons in the Java OSS, and proprietry, communities. A clear and
>> planned migration strategy for all our modules is needed.
> 
> 
> I accept that by its nature Commons is going to cause problems every
> time they release. We're going to be a frequent location for classpath
> clash problems. It's not JVM relevant though, it happens every time we
> release anything so the version you would need in the package name is
> the Commons major version, not the jdk version.
> 
> I think we should declare that new development will be on 1.5 -
> building 1.5 only jars. Anyone trying to use them on 1.4 and before is
> going to get a nice error and we can start exploring new JDK features
> like regular expressions *sarc :) *. Then we can stick with it until
> 1.8 is in beta or something.
> 
> Hen
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
> 
> 

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