commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gary Gregory <>
Subject Re: [RNG][ALL] Official vs "courtesy" code ?
Date Fri, 25 Nov 2016 19:43:37 GMT
Catching up on email... below...

On Thu, Nov 24, 2016 at 6:14 PM, Gilles <>

> On Thu, 24 Nov 2016 10:01:11 -0800, Gary Gregory wrote:
>> Preface: This thread, the questions it contains, as well as other recent
>> emails in general feels like the result of the normal learning curve one
>> must go through when dealing with a Maven multi-module project. This is
>> time well-spent IMO as most non-trivial (>1 jar) projects are multi-module
>> projects.
> The problem, IIUC the below, is that the modules in "Commons RNG"
> do not fit the intent of modules as used for a "Commons" component
> (as per your description).
> It would be more enlightening to use "Commons RNG" as the actual
> use-case.
> Now for the meat:
>> Strictly speaking, Apache Commons (and all Apache projects) release
>> sources
>> as the official release artifacts on Apache "dist" servers. Any binary
>> files we provide are a convenience whether on Apache servers or Maven
>> Central.
>> That means that ALL sources for a component (Apache Commons RNG in this
>> case) must be released in the -src ZIPs and GZs. I'd like to hear a good
>> reason not to do that. If a module is not ready for prime time, then I
>> suppose it could either be excluded or packaged in an module and package
>> with an appropriate artifact ID and name (like .ea/-early-access or
>> .experimental/-experimental).
>> It makes the most sense if the -bin version of a component contains the
>> result of building what is in all of the -src ZIP/GZ.
> I did not mean otherwise.
> I propose to release (1), (2), (3) and (4), the same source for -src
> and -bin archives (and for Nexus).
> I propose to not release (5) and (6): users/developers willing to get
> that code would need to check out the repository (and they can generate
> their "own" JARs if they want to run the code).
> So that would be a "no" to (a).
> Is it now a "yes", with the above clarification?

So your intent is to have Maven modules in the repo that stay in the repo
and that do not make it into jars, the -src and the -bin? If so, I think it
would be clearer to have those modules in a branch so they are not in 1.0.
But that's just own my noodle works. That would make it crystal clear that
these modules are not ready for prime time. BTW, no matter how many
modules/jars, there should be one -bin and one -src (well two if you count
them as pairs of ZIP/GZ files).

>> "[Rationale is that it would allow to make changes without
>>    bothering about compatibility with _unintended_ uses.]"
>> You should make it clear which module you guaranteed binary compatibility.
>> For example, in Log4j 2 we do our utmost to keep the API module 100% BC.
>> For all other modules (there are a few), we make no such guarantee but
>> also
>> try not to make our user's life difficult.
> That's a reason why I advocated to not mix in the same components
> modules that are not at the same level of development.
> In "Commons RNG", my perception of (1), (2), (3) is that they
> deserve a 1.0 release (as per "do-ocracy").
> My perception of (4) is that it deserves a 0.8 release because
>  * it provides useful stuff, such as Gaussian sampling, but
>  * it is perhaps not as finalize ("beautiful") in terms of
>    design (but even so, I won't be able to do more at this
>    point without feedback, and further delaying the release
>    waiting for feedback that may never come is not an option).

One Commons component (like [rng]) should release one version of all it's
modules at a time. That's how all of the other multi-module Commons
component do it and that's a sane approach IMO.

Releasing different versions of modules for a component is going to be
quite complicated and I am not sure it fits into our current model where
you can get one -src and one -bin file for a release. You'd then need other
-bin and -src files for these alpha modules. Well, you could mess with
assembly configs...

All of this and IMO: You could release 1.0 with what is solid and THEN
release 1.1-alpha1 with the extra modules.


> I cannot imagine that you'd want to provide 100% BC for a performance
>> measurement or examples module. It seems obvious to me, but you might as
>> well state it front if you think there could be room for confusion.
> I feel that the confusion would come if the concerned code is
> released.
> Absent that, no basis for complaint. :-)
> Repository is "provided as-is".
> For (b), that's a recipe for confusion and guaranteed questions on the ML
>> or bug reports in JIRA. Especially when it is easier to release to Nexus
>> than it is manually copying files around SVN (or writing a script to do
>> so).
> OK. I tried to be overly nice to users.
> Let them install "git"...
> For (c), that's another recipe for confusion. Apache Commons is special in
>> the sense that it is ONE Apache project that releases COMPONENTS like
>> Apache Commons IO, Apache Commons Lang and so on. When a component is
>> released, all modules it contains come along for the ride. Anything else
>> is
>> going to be a mess IMO.
> I don't really agree that one size fits all; even if this (same
> version for all modules) is the simplest, it is not the most
> adequate to convey the state of the corresponding code; version
> numbers should convey that, and it is misleading to keep the
> versions in sync when it does not reflect an actual change.
> I think that is a fundamental flaw in the tacitly applied
> policy (since Stian stated that it was not a strict rule).
> A 1.0 release is not only the first release but it is also a MAJOR release,
>> setting the public APIs in stone for 1.x.
> Fine with that.
> Breaking BC in a public API means
>> a major version change, a package change, and matching artifact ID change.
>> That's how we avoid jar hell.
> No problem with that.
> Noe that you get to define what public means BTW, this and that module but
>> not this other one. Even within a module you can make it clear what APIs
>> are public by "hidding" private APIs in specially named packages (IIRC,
>> Eclipse uses ".internal." for example).
> In "Commons RNG" there is not much to hide.
> Initially, I wanted to "force" the use of the "RandomSource" factory;
> but then if someone wants to use "new ISAACRandom(new int[] {1, 2})",
> I wondered why not.
> If you really want to push to a 1.0 and some of the code is not ready, you
>> can do that but you really should move that code to "I'm an experiment"
>> package. Then when that code is ready, you can release a 2.0 version with
>> the new shiny code in a public package. Or you could COPY it to to the
>> public package in a 1.x release, YMMV. It may seem like I am contradicting
>> myself but there are many ways to do this and play nice by BC rules.
> Confusing indeed; above you implied we can break compatibility with (5)
> and (6), and here you say we should release a new major version...
> My proposal is much simpler; let's not release that code.
> It would still be referred to in the "userguide" (in the sections
> about performance and quality).
> Gilles
>> I hope this helps!
>> Gary
>> On Thu, Nov 24, 2016 at 6:05 AM, Gilles <>
>> wrote:
>> Hi.
>>> The "Commons RNG" component (in the "Apache Commons" sense),
>>> consists of the following modules (in the "maven" sense) that
>>> provide Java code:
>>>  (1) commons-rng-client-api
>>>  (2) commons-rng-core
>>>  (3) commons-rng-simple
>>>  (4) commons-rng-sampling
>>>  (5) commons-rng-jmh
>>>  (6) commons-rng-examples
>>> One could see the RNG low-level "library" as composed of (1),
>>> (2) and (3).
>>> (4) is higher-level; it depends solely on the "UniformRandomProvider"
>>>     interface defined in (1).
>>> (5) does not provide any functionality to application developers.
>>> (6) contains working code that is either of interest to "Commons
>>>     RNG" contributors (for running the "stress" tests) or currently,
>>>     fairly trivial (and not recommended) examples of use of the
>>>     "library".
>>> Questions:
>>> a. Is it OK if the official release does not contain (5) and (6)?
>>>    [Rationale is that it would allow to make changes without
>>>    bothering about compatibility with _unintended_ uses.]
>>> b. If so, is it still OK to provide JARs for them via the web site
>>>    (but not upload them to Nexus)?
>>> c. Is it OK that the modules have different versions (reflecting
>>>    the perceived status of development)?
>>>    [This is related to the "commons-rng-sampling" issue of the
>>>    post with subject "Ralease policy for version < 1".]
> ---------------------------------------------------------------------
> To unsubscribe, e-mail:
> For additional commands, e-mail:

E-Mail: |
Java Persistence with Hibernate, Second Edition

JUnit in Action, Second Edition

Spring Batch in Action

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