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?
"[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).
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
<gil...@harfang.homelinux.org>
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: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
