You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Gilles <gi...@harfang.homelinux.org> on 2016/11/24 14:05:56 UTC
[RNG][ALL] Official vs "courtesy" code ?
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-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [RNG][ALL] Official vs "courtesy" code ?
Posted by Gilles <gi...@harfang.homelinux.org>.
Hi J�rg.
On Fri, 25 Nov 2016 15:25:09 +0100, J�rg Schaible wrote:
> 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".]
>
> c) does not make much sense to me. Even if we get it out of the door
> with
> out tooling, how will users find version 0.8 on our web site if it
> was part
> of release 1.0?
Perhaps what makes sense is to consider that it is each module
that is actually released (through a "bundled vote").
> What if we need a maintenance release 0.8.1 ... do we also
> need 1.0.1 for the rest?
No (if version numbers are supposed to mean something).
> If not, why release it together with 1.0 at all? Or
> why not simply have an own component as Gilles requested in first
> place?
Sure, that would be a solution in line of current practice.
And in effect letting modules live their own life would have the
same effect.
The choice (module vs component) is then more a matter of community
(i.e. do the same people perform the development of those modules)?
Regards,
Gilles
>
> Cheers,
> J�rg
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [RNG][ALL] Official vs "courtesy" code ?
Posted by Jörg Schaible <jo...@bpm-inspire.com>.
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".]
c) does not make much sense to me. Even if we get it out of the door with
out tooling, how will users find version 0.8 on our web site if it was part
of release 1.0? What if we need a maintenance release 0.8.1 ... do we also
need 1.0.1 for the rest? If not, why release it together with 1.0 at all? Or
why not simply have an own component as Gilles requested in first place?
Cheers,
J�rg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [RNG][ALL] Official vs "courtesy" code ?
Posted by Gary Gregory <ga...@gmail.com>.
Catching up on email... below...
On Thu, Nov 24, 2016 at 6:14 PM, Gilles <gi...@harfang.homelinux.org>
wrote:
> 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.
Gary
>
> 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 <gi...@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-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
Java Persistence with Hibernate, Second Edition
<https://www.amazon.com/gp/product/1617290459/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459&linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1617290459>
JUnit in Action, Second Edition
<https://www.amazon.com/gp/product/1935182021/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021&linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182021>
Spring Batch in Action
<https://www.amazon.com/gp/product/1935182951/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951&linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%7Blink_id%7D%7D%22%3ESpring+Batch+in+Action>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182951>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory
Re: [RNG][ALL] Official vs "courtesy" code ?
Posted by Gilles <gi...@harfang.homelinux.org>.
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
> <gi...@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-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [RNG][ALL] Official vs "courtesy" code ?
Posted by Gilles <gi...@harfang.homelinux.org>.
On Fri, 25 Nov 2016 11:55:57 -0800, Gary Gregory wrote:
> On Fri, Nov 25, 2016 at 7:14 AM, Gilles
> <gi...@harfang.homelinux.org>
> wrote:
>
>> Hello.
>>
>> Thanks for all the replies.
>> However, it seems that when a project could make use of the
>> flexibility provided by modularization, there are objections
>> to really embrace it:
>> * Some don't like a partial release
>> * Some don't like different version numbers
>> * Some don't like releasing codes at different levels of
>> "achievement"
>>
>> Clearly there is no consensus.
>>
>> IMHO, a particular useful feature of modularization is to
>> allow the respective versions to reflect the actual state of
>> the code contained in the corresponding module.
>> Otherwise the (single) version is misleading for some of
>> modules and meaningless for others.
>>
>> I can understand that version varying across modules requires
>> careful attention; but is there a problem in principle?
>> Won't tools such as Clirr readily spot failures to comply with
>> compatibility requirements?
>>
>> Using again the practical example, and trying to mix and match
>> opposite POVs, here is a suggestion.
>>
>> Release all "productive" functionality:
>> commons-rng-client-api -> 1.0
>> commons-rng-core -> 1.0
>> commons-rng-simple -> 1.0
>> commons-rng-sampling -> 0.8
>>
>> Question for the latter (from the other thread):
>> When "sampling v1.0" is released, can it break compatibility
>> with "sampling v0.8" ?
>>
>
> I guess not.
I understand thus that version numbers below 1 are utterly useless.
In effect, if there is a release of package
org.apache.commons.rng.sampling
with version, say, 0.8.
Then when version 1.0 is released, the package must change to
org.apache.commons.rng1.sampling
unless ...
> You could also remove any jar hell risk by packaging 0.8 in an
> .alpha. package.
... everything released with version < 1 must be in an "alpha"
package
org.apache.commons.rng.alpha.sampling
Is that a rule? [Anyways, I find it prone to confusion.]
All in all, you confirm that having modules is not giving
any flexibility in release management: codes that would not
strictly require being released together, are forced to
share the same version number.
[The unavoidable consequence is that another component (a.k.a.
"RNG Utils") was the simple and flexible approach.]
On a slightly different note, by assuming that 0.8 would fit
as a version, I might have made it look like the sampling
package is not ready, and you implied that it should not be
released.
Quite the contrary, it is certainly not worse that code
released many times over in Commons Math.
And, with the new 64-bits generators, the continuous
distribution samplers should even be faster.
I can only repeat a statement of fact: I worked on the
design much less than I did for the other modules (a
couple of weeks vs almost a year).
But the functionality is quite usable (as it was deemed
usable in Commons Math).
I'd say that we have to choose between
(a) allowing different versions in modules (and IIRC Stian
said that no Apache rule does forbids it), or
(b) assuming that version numbers are meaningless (in cases
like "Commons RNG") beyond being a counter, or
(c) when (b) happens requires the creation of a new
component.
I've no blocking problem with option (b); just let me know.
Gilles
>
> Gary
>
>
>>
>> Release code only useful for internal development (e.g.
>> checking that a contribution does degrade performance),
>> with a suffix that indicates so
>> commons-rng-jmh -> 1.0-dev
>>
>> There is no obligation to provide benchmarking code, is there?
>> Publishing results on the web site is already much more than
>> other components do.
>>
>> Release usage examples with a version number and suffix
>> indicating that no comptatiblity is to be expected:
>> commons-rng-examples -> 0.0.1-beta
>>
>> [Is there a better "suffix"?]
>>
>> WDYT?
>>
>>
>> Regards,
>> Gilles
>>
>>
>>
>> On Fri, 25 Nov 2016 13:34:04 +0100, J�rg Schaible wrote:
>>
>>> Hi,
>>>
>>> Stian Soiland-Reyes wrote:
>>>
>>> I think I'll tend towards agreeing with Jochen here, rather get
>>> half the
>>>> modules out early than fight ourselves with versioning workarounds
>>>> if the
>>>> rest of the modules are not ready for prime time.
>>>>
>>>> However I see concerns of selective "part releases" and
>>>> reproducible
>>>> builds, so I would do this using Maven profiles - the release
>>>> profile can
>>>> have a smaller <modules> set.
>>>>
>>>> I then think all the modules that appear in the src release should
>>>> also
>>>> go
>>>> to Nexus as binaries, even if they are more exotic "internal"
>>>> modules. I
>>>> would not mess around with selective deployment as it is a recipe
>>>> for
>>>> maintenance nightmare and manual mistakes.
>>>>
>>>> It only gets tricky if the leftover modules get a release cycle of
>>>> their
>>>> own.
>>>>
>>>> It is OK if the -bin release don't have all modules, that is more
>>>> of a
>>>> convenience of jars that are useful out of the box.
>>>>
>>>
>>> The -src artifact is a different case. It should contain anything
>>> independent of the published modules' artifacts (and it can,
>>> because it
>>> depends on the file patterns in the assembly). It is always a
>>> hassle if
>>> you
>>> have no direct possibility to fetch the matching source of the
>>> examples
>>> (and
>>> even the JMH stuff) for an individual release. Directing users to
>>> GIT is
>>> not
>>> very convenient.
>>>
>>> Cheers,
>>> J�rg
>>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [RNG][ALL] Official vs "courtesy" code ?
Posted by Gary Gregory <ga...@gmail.com>.
On Fri, Nov 25, 2016 at 7:14 AM, Gilles <gi...@harfang.homelinux.org>
wrote:
> Hello.
>
> Thanks for all the replies.
> However, it seems that when a project could make use of the
> flexibility provided by modularization, there are objections
> to really embrace it:
> * Some don't like a partial release
> * Some don't like different version numbers
> * Some don't like releasing codes at different levels of
> "achievement"
>
> Clearly there is no consensus.
>
> IMHO, a particular useful feature of modularization is to
> allow the respective versions to reflect the actual state of
> the code contained in the corresponding module.
> Otherwise the (single) version is misleading for some of
> modules and meaningless for others.
>
> I can understand that version varying across modules requires
> careful attention; but is there a problem in principle?
> Won't tools such as Clirr readily spot failures to comply with
> compatibility requirements?
>
> Using again the practical example, and trying to mix and match
> opposite POVs, here is a suggestion.
>
> Release all "productive" functionality:
> commons-rng-client-api -> 1.0
> commons-rng-core -> 1.0
> commons-rng-simple -> 1.0
> commons-rng-sampling -> 0.8
>
> Question for the latter (from the other thread):
> When "sampling v1.0" is released, can it break compatibility
> with "sampling v0.8" ?
>
I guess not. You could also remove any jar hell risk by packaging 0.8 in an
.alpha. package.
Gary
>
> Release code only useful for internal development (e.g.
> checking that a contribution does degrade performance),
> with a suffix that indicates so
> commons-rng-jmh -> 1.0-dev
>
> There is no obligation to provide benchmarking code, is there?
> Publishing results on the web site is already much more than
> other components do.
>
> Release usage examples with a version number and suffix
> indicating that no comptatiblity is to be expected:
> commons-rng-examples -> 0.0.1-beta
>
> [Is there a better "suffix"?]
>
> WDYT?
>
>
> Regards,
> Gilles
>
>
>
> On Fri, 25 Nov 2016 13:34:04 +0100, Jörg Schaible wrote:
>
>> Hi,
>>
>> Stian Soiland-Reyes wrote:
>>
>> I think I'll tend towards agreeing with Jochen here, rather get half the
>>> modules out early than fight ourselves with versioning workarounds if the
>>> rest of the modules are not ready for prime time.
>>>
>>> However I see concerns of selective "part releases" and reproducible
>>> builds, so I would do this using Maven profiles - the release profile can
>>> have a smaller <modules> set.
>>>
>>> I then think all the modules that appear in the src release should also
>>> go
>>> to Nexus as binaries, even if they are more exotic "internal" modules. I
>>> would not mess around with selective deployment as it is a recipe for
>>> maintenance nightmare and manual mistakes.
>>>
>>> It only gets tricky if the leftover modules get a release cycle of their
>>> own.
>>>
>>> It is OK if the -bin release don't have all modules, that is more of a
>>> convenience of jars that are useful out of the box.
>>>
>>
>> The -src artifact is a different case. It should contain anything
>> independent of the published modules' artifacts (and it can, because it
>> depends on the file patterns in the assembly). It is always a hassle if
>> you
>> have no direct possibility to fetch the matching source of the examples
>> (and
>> even the JMH stuff) for an individual release. Directing users to GIT is
>> not
>> very convenient.
>>
>> Cheers,
>> Jörg
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
Java Persistence with Hibernate, Second Edition
<https://www.amazon.com/gp/product/1617290459/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459&linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1617290459>
JUnit in Action, Second Edition
<https://www.amazon.com/gp/product/1935182021/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021&linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182021>
Spring Batch in Action
<https://www.amazon.com/gp/product/1935182951/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951&linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%7Blink_id%7D%7D%22%3ESpring+Batch+in+Action>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182951>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory
Re: [RNG][ALL] Official vs "courtesy" code ?
Posted by Gilles <gi...@harfang.homelinux.org>.
Hello.
Thanks for all the replies.
However, it seems that when a project could make use of the
flexibility provided by modularization, there are objections
to really embrace it:
* Some don't like a partial release
* Some don't like different version numbers
* Some don't like releasing codes at different levels of
"achievement"
Clearly there is no consensus.
IMHO, a particular useful feature of modularization is to
allow the respective versions to reflect the actual state of
the code contained in the corresponding module.
Otherwise the (single) version is misleading for some of
modules and meaningless for others.
I can understand that version varying across modules requires
careful attention; but is there a problem in principle?
Won't tools such as Clirr readily spot failures to comply with
compatibility requirements?
Using again the practical example, and trying to mix and match
opposite POVs, here is a suggestion.
Release all "productive" functionality:
commons-rng-client-api -> 1.0
commons-rng-core -> 1.0
commons-rng-simple -> 1.0
commons-rng-sampling -> 0.8
Question for the latter (from the other thread):
When "sampling v1.0" is released, can it break compatibility
with "sampling v0.8" ?
Release code only useful for internal development (e.g.
checking that a contribution does degrade performance),
with a suffix that indicates so
commons-rng-jmh -> 1.0-dev
There is no obligation to provide benchmarking code, is there?
Publishing results on the web site is already much more than
other components do.
Release usage examples with a version number and suffix
indicating that no comptatiblity is to be expected:
commons-rng-examples -> 0.0.1-beta
[Is there a better "suffix"?]
WDYT?
Regards,
Gilles
On Fri, 25 Nov 2016 13:34:04 +0100, J�rg Schaible wrote:
> Hi,
>
> Stian Soiland-Reyes wrote:
>
>> I think I'll tend towards agreeing with Jochen here, rather get half
>> the
>> modules out early than fight ourselves with versioning workarounds
>> if the
>> rest of the modules are not ready for prime time.
>>
>> However I see concerns of selective "part releases" and reproducible
>> builds, so I would do this using Maven profiles - the release
>> profile can
>> have a smaller <modules> set.
>>
>> I then think all the modules that appear in the src release should
>> also go
>> to Nexus as binaries, even if they are more exotic "internal"
>> modules. I
>> would not mess around with selective deployment as it is a recipe
>> for
>> maintenance nightmare and manual mistakes.
>>
>> It only gets tricky if the leftover modules get a release cycle of
>> their
>> own.
>>
>> It is OK if the -bin release don't have all modules, that is more of
>> a
>> convenience of jars that are useful out of the box.
>
> The -src artifact is a different case. It should contain anything
> independent of the published modules' artifacts (and it can, because
> it
> depends on the file patterns in the assembly). It is always a hassle
> if you
> have no direct possibility to fetch the matching source of the
> examples (and
> even the JMH stuff) for an individual release. Directing users to GIT
> is not
> very convenient.
>
> Cheers,
> J�rg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [RNG][ALL] Official vs "courtesy" code ?
Posted by Jörg Schaible <jo...@bpm-inspire.com>.
Hi,
Stian Soiland-Reyes wrote:
> I think I'll tend towards agreeing with Jochen here, rather get half the
> modules out early than fight ourselves with versioning workarounds if the
> rest of the modules are not ready for prime time.
>
> However I see concerns of selective "part releases" and reproducible
> builds, so I would do this using Maven profiles - the release profile can
> have a smaller <modules> set.
>
> I then think all the modules that appear in the src release should also go
> to Nexus as binaries, even if they are more exotic "internal" modules. I
> would not mess around with selective deployment as it is a recipe for
> maintenance nightmare and manual mistakes.
>
> It only gets tricky if the leftover modules get a release cycle of their
> own.
>
> It is OK if the -bin release don't have all modules, that is more of a
> convenience of jars that are useful out of the box.
The -src artifact is a different case. It should contain anything
independent of the published modules' artifacts (and it can, because it
depends on the file patterns in the assembly). It is always a hassle if you
have no direct possibility to fetch the matching source of the examples (and
even the JMH stuff) for an individual release. Directing users to GIT is not
very convenient.
Cheers,
J�rg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [RNG][ALL] Official vs "courtesy" code ?
Posted by Stian Soiland-Reyes <st...@apache.org>.
I think I'll tend towards agreeing with Jochen here, rather get half the
modules out early than fight ourselves with versioning workarounds if the
rest of the modules are not ready for prime time.
However I see concerns of selective "part releases" and reproducible
builds, so I would do this using Maven profiles - the release profile can
have a smaller <modules> set.
I then think all the modules that appear in the src release should also go
to Nexus as binaries, even if they are more exotic "internal" modules. I
would not mess around with selective deployment as it is a recipe for
maintenance nightmare and manual mistakes.
It only gets tricky if the leftover modules get a release cycle of their
own.
It is OK if the -bin release don't have all modules, that is more of a
convenience of jars that are useful out of the box. I've been thinking for
Commons RDF it would make sense to have a bin with the commons-rdf-api.jar
and commons-rdf-simple.jar as they have no external dependencies - the
remaining Integration modules require a large set of deps and mostly useful
through Maven.
(OSGi folks might still like the extra jars as they are bundles)
On 25 Nov 2016 11:47 am, "Jochen Wiedmann" <jo...@gmail.com>
wrote:
> Hi, Gary,
>
>
> I humbly disagree on your response to Gilles questions. In more detail:
>
>
> 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.]
>
> A release is a release, because it fulfills the typical requirements
> (ASL licensed, source first, binary is for convenience only,
> LICENSE.txt, and NOTICE.txt, etc.)
> and, most importantly, because the PMC endorses it as such.
>
> I can't think of any reason, why the PMC should refuse a release, if
> it fulfills the requirement, just because the source release can be
> used to build four jars only, and not six. At least, I'd be glad to
> vote +1 in such a case.
>
> That being said, and having had the experience of a multi-module
> project (Apache RAT) in the past, I strongly recommend that RNG
>
> - abstains from full releases (all six jar files) and
> - starts by pushing out single jar files by default (in whatever order
> seems to make sense). (Possibly more than one at once, okay.)
>
> Otherwise, I have learned that the hurdle to push out a release can
> become overwhelming, and leads to deferring releases endlessly. Forget
> "release early, release often".
>
> Besides, you'd have to maintain varying build scripts, or even worse:
> Create individual build scripts, depending on what is being released.
> Not, what I would like to see in a project of mine.
>
> b. If so, is it still OK to provide JARs for them via the web site
> (but not upload them to Nexus)?
>
> For all practical purposes, Nexus is more important nowadays for
> distributing binary jars, than the ASF web site. The source archives
> are another story, of course, as they constitute the actual release.
> Those *must* be available from the web site.
>
>
> 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".]
>
> If they are successfully voted upon: Why not?
>
> Jochen
>
>
> On Thu, Nov 24, 2016 at 7:01 PM, Gary Gregory <ga...@gmail.com>
> 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.
> >
> > 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.
> >
> > So that would be a "no" to (a).
> >
> > "[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.
> >
> > 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.
> >
> > 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).
> >
> > 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.
> >
> > 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. 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.
> >
> > 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).
> >
> > 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.
> >
> > I hope this helps!
> >
> > Gary
> >
> > On Thu, Nov 24, 2016 at 6:05 AM, Gilles <gi...@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-unsubscribe@commons.apache.org
> >> For additional commands, e-mail: dev-help@commons.apache.org
> >>
> >>
> >
> >
> > --
> > E-Mail: garydgregory@gmail.com | ggregory@apache.org
> > Java Persistence with Hibernate, Second Edition
> > <https://www.amazon.com/gp/product/1617290459/ref=as_li_
> tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459&
> linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8>
> >
> > <http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=
> 1617290459>
> > JUnit in Action, Second Edition
> > <https://www.amazon.com/gp/product/1935182021/ref=as_li_
> tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021&
> linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22
> >
> >
> > <http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=
> 1935182021>
> > Spring Batch in Action
> > <https://www.amazon.com/gp/product/1935182951/ref=as_li_
> tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951&
> linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%
> 7Blink_id%7D%7D%22%3ESpring+Batch+in+Action>
> > <http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=
> 1935182951>
> > Blog: http://garygregory.wordpress.com
> > Home: http://garygregory.com/
> > Tweet! http://twitter.com/GaryGregory
>
>
>
> --
> The next time you hear: "Don't reinvent the wheel!"
>
> http://www.keystonedevelopment.co.uk/wp-content/uploads/2014/10/
> evolution-of-the-wheel-300x85.jpg
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
Re: [RNG][ALL] Official vs "courtesy" code ?
Posted by Gary Gregory <ga...@gmail.com>.
On Fri, Nov 25, 2016 at 3:45 AM, Jochen Wiedmann <jo...@gmail.com>
wrote:
> Hi, Gary,
>
>
> I humbly disagree on your response to Gilles questions. In more detail:
>
Humility not required, let me have it! ;-) [or let the technical points
have it]
>
>
> 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.]
>
> A release is a release, because it fulfills the typical requirements
> (ASL licensed, source first, binary is for convenience only,
> LICENSE.txt, and NOTICE.txt, etc.)
> and, most importantly, because the PMC endorses it as such.
>
> I can't think of any reason, why the PMC should refuse a release, if
> it fulfills the requirement, just because the source release can be
> used to build four jars only, and not six. At least, I'd be glad to
> vote +1 in such a case.
>
> That being said, and having had the experience of a multi-module
> project (Apache RAT) in the past, I strongly recommend that RNG
>
> - abstains from full releases (all six jar files) and
> - starts by pushing out single jar files by default (in whatever order
> seems to make sense). (Possibly more than one at once, okay.)
>
Are you suggesting that an uber jar be available? That's always a good
thing IMO. I find the two list items above in contradiction with each other.
>
> Otherwise, I have learned that the hurdle to push out a release can
> become overwhelming, and leads to deferring releases endlessly. Forget
> "release early, release often".
>
We've recently seen some multi-module releases: Commons JCS and
Commons Weaver. It's harder, sure but there is experience around here to
help.
>
> Besides, you'd have to maintain varying build scripts, or even worse:
> Create individual build scripts, depending on what is being released.
> Not, what I would like to see in a project of mine.
>
> b. If so, is it still OK to provide JARs for them via the web site
> (but not upload them to Nexus)?
>
> For all practical purposes, Nexus is more important nowadays for
> distributing binary jars, than the ASF web site. The source archives
> are another story, of course, as they constitute the actual release.
> Those *must* be available from the web site.
>
I agree.
Gary
>
>
> 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".]
>
> If they are successfully voted upon: Why not?
>
> Jochen
>
>
> On Thu, Nov 24, 2016 at 7:01 PM, Gary Gregory <ga...@gmail.com>
> 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.
> >
> > 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.
> >
> > So that would be a "no" to (a).
> >
> > "[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.
> >
> > 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.
> >
> > 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).
> >
> > 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.
> >
> > 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. 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.
> >
> > 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).
> >
> > 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.
> >
> > I hope this helps!
> >
> > Gary
> >
> > On Thu, Nov 24, 2016 at 6:05 AM, Gilles <gi...@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-unsubscribe@commons.apache.org
> >> For additional commands, e-mail: dev-help@commons.apache.org
> >>
> >>
> >
> >
> > --
> > E-Mail: garydgregory@gmail.com | ggregory@apache.org
> > Java Persistence with Hibernate, Second Edition
> > <https://www.amazon.com/gp/product/1617290459/ref=as_li_
> tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459&
> linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8>
> >
> > <http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=
> 1617290459>
> > JUnit in Action, Second Edition
> > <https://www.amazon.com/gp/product/1935182021/ref=as_li_
> tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021&
> linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22
> >
> >
> > <http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=
> 1935182021>
> > Spring Batch in Action
> > <https://www.amazon.com/gp/product/1935182951/ref=as_li_
> tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951&
> linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%
> 7Blink_id%7D%7D%22%3ESpring+Batch+in+Action>
> > <http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=
> 1935182951>
> > Blog: http://garygregory.wordpress.com
> > Home: http://garygregory.com/
> > Tweet! http://twitter.com/GaryGregory
>
>
>
> --
> The next time you hear: "Don't reinvent the wheel!"
>
> http://www.keystonedevelopment.co.uk/wp-content/uploads/2014/10/
> evolution-of-the-wheel-300x85.jpg
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
Java Persistence with Hibernate, Second Edition
<https://www.amazon.com/gp/product/1617290459/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459&linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1617290459>
JUnit in Action, Second Edition
<https://www.amazon.com/gp/product/1935182021/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021&linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182021>
Spring Batch in Action
<https://www.amazon.com/gp/product/1935182951/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951&linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%7Blink_id%7D%7D%22%3ESpring+Batch+in+Action>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182951>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory
Re: [RNG][ALL] Official vs "courtesy" code ?
Posted by Jochen Wiedmann <jo...@gmail.com>.
Hi, Gary,
I humbly disagree on your response to Gilles questions. In more detail:
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.]
A release is a release, because it fulfills the typical requirements
(ASL licensed, source first, binary is for convenience only,
LICENSE.txt, and NOTICE.txt, etc.)
and, most importantly, because the PMC endorses it as such.
I can't think of any reason, why the PMC should refuse a release, if
it fulfills the requirement, just because the source release can be
used to build four jars only, and not six. At least, I'd be glad to
vote +1 in such a case.
That being said, and having had the experience of a multi-module
project (Apache RAT) in the past, I strongly recommend that RNG
- abstains from full releases (all six jar files) and
- starts by pushing out single jar files by default (in whatever order
seems to make sense). (Possibly more than one at once, okay.)
Otherwise, I have learned that the hurdle to push out a release can
become overwhelming, and leads to deferring releases endlessly. Forget
"release early, release often".
Besides, you'd have to maintain varying build scripts, or even worse:
Create individual build scripts, depending on what is being released.
Not, what I would like to see in a project of mine.
b. If so, is it still OK to provide JARs for them via the web site
(but not upload them to Nexus)?
For all practical purposes, Nexus is more important nowadays for
distributing binary jars, than the ASF web site. The source archives
are another story, of course, as they constitute the actual release.
Those *must* be available from the web site.
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".]
If they are successfully voted upon: Why not?
Jochen
On Thu, Nov 24, 2016 at 7:01 PM, Gary Gregory <ga...@gmail.com> 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.
>
> 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.
>
> So that would be a "no" to (a).
>
> "[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.
>
> 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.
>
> 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).
>
> 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.
>
> 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. 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.
>
> 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).
>
> 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.
>
> I hope this helps!
>
> Gary
>
> On Thu, Nov 24, 2016 at 6:05 AM, Gilles <gi...@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-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>
>
> --
> E-Mail: garydgregory@gmail.com | ggregory@apache.org
> Java Persistence with Hibernate, Second Edition
> <https://www.amazon.com/gp/product/1617290459/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459&linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8>
>
> <http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1617290459>
> JUnit in Action, Second Edition
> <https://www.amazon.com/gp/product/1935182021/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021&linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22>
>
> <http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182021>
> Spring Batch in Action
> <https://www.amazon.com/gp/product/1935182951/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951&linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%7Blink_id%7D%7D%22%3ESpring+Batch+in+Action>
> <http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182951>
> Blog: http://garygregory.wordpress.com
> Home: http://garygregory.com/
> Tweet! http://twitter.com/GaryGregory
--
The next time you hear: "Don't reinvent the wheel!"
http://www.keystonedevelopment.co.uk/wp-content/uploads/2014/10/evolution-of-the-wheel-300x85.jpg
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [RNG][ALL] Official vs "courtesy" code ?
Posted by Gary Gregory <ga...@gmail.com>.
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.
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.
So that would be a "no" to (a).
"[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.
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.
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).
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.
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. 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.
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).
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.
I hope this helps!
Gary
On Thu, Nov 24, 2016 at 6:05 AM, Gilles <gi...@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-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
--
E-Mail: garydgregory@gmail.com | ggregory@apache.org
Java Persistence with Hibernate, Second Edition
<https://www.amazon.com/gp/product/1617290459/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1617290459&linkCode=as2&tag=garygregory-20&linkId=cadb800f39946ec62ea2b1af9fe6a2b8>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1617290459>
JUnit in Action, Second Edition
<https://www.amazon.com/gp/product/1935182021/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182021&linkCode=as2&tag=garygregory-20&linkId=31ecd1f6b6d1eaf8886ac902a24de418%22>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182021>
Spring Batch in Action
<https://www.amazon.com/gp/product/1935182951/ref=as_li_tl?ie=UTF8&camp=1789&creative=9325&creativeASIN=1935182951&linkCode=%7B%7BlinkCode%7D%7D&tag=garygregory-20&linkId=%7B%7Blink_id%7D%7D%22%3ESpring+Batch+in+Action>
<http:////ir-na.amazon-adsystem.com/e/ir?t=garygregory-20&l=am2&o=1&a=1935182951>
Blog: http://garygregory.wordpress.com
Home: http://garygregory.com/
Tweet! http://twitter.com/GaryGregory