Re: [all] Binaries for example modules
Maybe a bit late in the game, but still: In face of the fact, that we are already looking at a multi module project: Having all the examples within a dedicated module added into the hierarchy would allow us, to have it all, and still without burdening the RM: - keeping the examples current by compiling and executing/testing them during releases - maintaining arbitrary links from other modules sites/javadoc into the site generated by the examples - we may still avoid to distribute some of their artifacts, especially the binaries, by simply excluding them from install/deploy/release steps, which could done by properly configuring the install/deploy/release plugins within the examples pom. It shouldn't even be necessary, to have a profile for that. Just my 2 cents. The only thing, that might be of interest is the question, whether as part of the process, the examples module should produce and release kind of a source artifact, containing the *complete* source (with pom, src/main/** etc), or if we point the users simply to the version control URL, where they might check it out. Regards, Thomas On 09.08.2021 13:22, Matt Juntunen wrote: Advertising the examples at a higher level in the project site is better, so adding them to the user guide is an appropriate place. The question then is should the higher location point the user to the module site index, recommend downloading the source release which contains all the examples (and not having the module site published), or both. I would say both. I do not think pushing the artifacts to Maven Central is useful +1. I think we're all agreed on this point. -Matt J On Sun, Aug 8, 2021 at 5:38 PM Alex Herbert wrote: On Fri, 6 Aug 2021 at 04:01, Gilles Sadowski wrote: Le ven. 6 août 2021 à 04:01, Matt Juntunen a écrit : Gilles, I do _not_ ask any work to be done in order to complicate the release process and/or review. My question was (cf. above and the other thread) whether singling out the "examples" module has any benefit (apart from saving a few bytes on Maven Central). Yes, I believe it is beneficial. If nothing else, it keeps maven central and the project site uncluttered and reduces the chance of user confusion. I do not see where the problem is supposed to be (with Maven Central). But, either way, it's not worth fighting over it, as long as the examples are kept in sync with the code (and this is done at the lastest as part of the current release process). [The counter-example is "Commons Math", where the code examples were not kept up to date with the main code...] For the site, I believe that the examples should be there, as they are show-cases (for users!) of fully-working applications.[1] I do not think that the layout of the site for maven modules is very friendly for browsing the source. You are required to traverse down the hierarchy to the module site index, then click the project reports link then either the javadoc or xref reports. It takes a lot of finding and may not be found at all by a new user of the modular site layout. Advertising the examples at a higher level in the project site is better, so adding them to the user guide is an appropriate place. The question then is should the higher location point the user to the module site index, recommend downloading the source release which contains all the examples (and not having the module site published), or both. I do not think pushing the artifacts to Maven Central is useful as the applications are either developer testing tools or integration test demos. These are not of use to be linked by a third party as a dependency, and given they have no binary compatibility guarantee it would be unwise to depend on them anyway. Gilles [1] See e.g. https://commons.apache.org/proper/commons-rng/commons-rng-examples/commons-rng-examples-quadrature/xref/index.html - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [all] Binaries for example modules
> Advertising > the examples at a higher level in the project site is better, so adding > them to the user guide is an appropriate place. The question then is should > the higher location point the user to the module site index, recommend > downloading the source release which contains all the examples (and not > having the module site published), or both. I would say both. > I do not think pushing the artifacts to Maven Central is useful +1. I think we're all agreed on this point. -Matt J On Sun, Aug 8, 2021 at 5:38 PM Alex Herbert wrote: > > On Fri, 6 Aug 2021 at 04:01, Gilles Sadowski wrote: > > > Le ven. 6 août 2021 à 04:01, Matt Juntunen a > > écrit : > > > > > > Gilles, > > > > > > > I do _not_ ask any work to be done in order to complicate the release > > > > process and/or review. > > > > My question was (cf. above and the other thread) whether singling out > > > > the "examples" module has any benefit (apart from saving a few bytes > > > > on Maven Central). > > > > > > Yes, I believe it is beneficial. If nothing else, it keeps maven > > > central and the project site uncluttered and reduces the chance of > > > user confusion. > > > > I do not see where the problem is supposed to be (with Maven Central). > > But, either way, it's not worth fighting over it, as long as the examples > > are kept in sync with the code (and this is done at the lastest as part > > of the current release process). [The counter-example is "Commons > > Math", where the code examples were not kept up to date with the > > main code...] > > For the site, I believe that the examples should be there, as they are > > show-cases (for users!) of fully-working applications.[1] > > > > I do not think that the layout of the site for maven modules is very > friendly for browsing the source. You are required to traverse down the > hierarchy to the module site index, then click the project reports link > then either the javadoc or xref reports. It takes a lot of finding and may > not be found at all by a new user of the modular site layout. Advertising > the examples at a higher level in the project site is better, so adding > them to the user guide is an appropriate place. The question then is should > the higher location point the user to the module site index, recommend > downloading the source release which contains all the examples (and not > having the module site published), or both. > > I do not think pushing the artifacts to Maven Central is useful as the > applications are either developer testing tools or integration test demos. > These are not of use to be linked by a third party as a dependency, and > given they have no binary compatibility guarantee it would be unwise to > depend on them anyway. > > > > > > Gilles > > > > [1] See e.g. > > https://commons.apache.org/proper/commons-rng/commons-rng-examples/commons-rng-examples-quadrature/xref/index.html > > > > - > > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > > For additional commands, e-mail: dev-h...@commons.apache.org > > > > - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [all] Binaries for example modules
On Fri, 6 Aug 2021 at 04:01, Gilles Sadowski wrote: > Le ven. 6 août 2021 à 04:01, Matt Juntunen a > écrit : > > > > Gilles, > > > > > I do _not_ ask any work to be done in order to complicate the release > > > process and/or review. > > > My question was (cf. above and the other thread) whether singling out > > > the "examples" module has any benefit (apart from saving a few bytes > > > on Maven Central). > > > > Yes, I believe it is beneficial. If nothing else, it keeps maven > > central and the project site uncluttered and reduces the chance of > > user confusion. > > I do not see where the problem is supposed to be (with Maven Central). > But, either way, it's not worth fighting over it, as long as the examples > are kept in sync with the code (and this is done at the lastest as part > of the current release process). [The counter-example is "Commons > Math", where the code examples were not kept up to date with the > main code...] > For the site, I believe that the examples should be there, as they are > show-cases (for users!) of fully-working applications.[1] > I do not think that the layout of the site for maven modules is very friendly for browsing the source. You are required to traverse down the hierarchy to the module site index, then click the project reports link then either the javadoc or xref reports. It takes a lot of finding and may not be found at all by a new user of the modular site layout. Advertising the examples at a higher level in the project site is better, so adding them to the user guide is an appropriate place. The question then is should the higher location point the user to the module site index, recommend downloading the source release which contains all the examples (and not having the module site published), or both. I do not think pushing the artifacts to Maven Central is useful as the applications are either developer testing tools or integration test demos. These are not of use to be linked by a third party as a dependency, and given they have no binary compatibility guarantee it would be unwise to depend on them anyway. > > Gilles > > [1] See e.g. > https://commons.apache.org/proper/commons-rng/commons-rng-examples/commons-rng-examples-quadrature/xref/index.html > > - > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > >
Re: [all] Binaries for example modules
Le ven. 6 août 2021 à 04:01, Matt Juntunen a écrit : > > Gilles, > > > I do _not_ ask any work to be done in order to complicate the release > > process and/or review. > > My question was (cf. above and the other thread) whether singling out > > the "examples" module has any benefit (apart from saving a few bytes > > on Maven Central). > > Yes, I believe it is beneficial. If nothing else, it keeps maven > central and the project site uncluttered and reduces the chance of > user confusion. I do not see where the problem is supposed to be (with Maven Central). But, either way, it's not worth fighting over it, as long as the examples are kept in sync with the code (and this is done at the lastest as part of the current release process). [The counter-example is "Commons Math", where the code examples were not kept up to date with the main code...] For the site, I believe that the examples should be there, as they are show-cases (for users!) of fully-working applications.[1] Gilles [1] See e.g. https://commons.apache.org/proper/commons-rng/commons-rng-examples/commons-rng-examples-quadrature/xref/index.html - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [all] Binaries for example modules
Gilles, > I do _not_ ask any work to be done in order to complicate the release > process and/or review. > My question was (cf. above and the other thread) whether singling out > the "examples" module has any benefit (apart from saving a few bytes > on Maven Central). Yes, I believe it is beneficial. If nothing else, it keeps maven central and the project site uncluttered and reduces the chance of user confusion. -Matt J On Thu, Aug 5, 2021 at 12:50 PM Alex Herbert wrote: > > On Thu, 5 Aug 2021 at 17:23, Gilles Sadowski wrote: > > > Hi. > > > > Le jeu. 5 août 2021 à 18:01, Alex Herbert a > > écrit : > > > > > > On Thu, 5 Aug 2021 at 14:07, Gilles Sadowski > > wrote: > > > > > > > Le jeu. 5 août 2021 à 14:08, Gary Gregory a > > > > écrit : > > > > > > > > > > I agree with Matt. > > > > > > > > Nobody seems to disagree (about not providing convenience *binaries* > > > > of the examples). > > > > My point was that the examples _must_ be part of the (source) release > > > > (with the caveat that they are not subject to BC), in the same way that > > > > unit tests are, because they could sometimes exercise the code in a way > > > > which the unit tests do not. > > > > Maybe I misunderstood Matt's proposal, which I thought was was to not > > > > release the examples (i.e. leaving them out of the release branch). > > > > > > > > > > If the release profile in the POM omits the examples modules then they > > will > > > not be released as binary jars to nexus, and the modules are omitted from > > > the site generation. The contents of the distribution release binary > > (zip, > > > tar.gz) are specified separately. So these can include all the source > > text > > > files from the examples. > > > > > > However if the examples modules are not in the POM hierarchy then the > > > binaries will not be built from the source as part of the release > > process. > > > It is possible to include the modules and skip the site generation for > > the > > > maven-site-plugin. I am not sure about skipping the maven-release-plugin. > > > It may be possible using the dryRun parameter but I would have to > > > investigate. > > > > > > If the build of the examples cannot be set-up to be verified during the > > > release process then this should be verified by the RM and any reviewers > > of > > > the release to ensure the examples do build from the source distribution. > > > > > > In the case of RNG this could involve adding a step to the release guide > > to > > > state that applications in all the example modules should be run to > > ensure > > > they compile with the API from the released code. The same can be added > > to > > > guidelines in the VOTE e-mail. > > > > > > Would this cover your requirement that the examples code is exercised? > > > > I do _not_ ask any work to be done in order to complicate the release > > process and/or review. > > My question was (cf. above and the other thread) whether singling out > > the "examples" module has any benefit (apart from saving a few bytes > > on Maven Central). > > > > I've just pushed an update to RNG to add more details on how to run the > examples. I will look at preparing a release without the examples modules > in the next few days. Ideally I would like to ensure the process builds the > binaries just to check it is possible but not add them Maven central or the > limited module reports to the site. Otherwise I am fine with a manual > verification step (that can be scripted) just to build and run each example. > > The examples are built using Jenkins so they should be kept current and > able to compile. Running them is not something done by the CI build. > > Alex > > > > > > > Best, > > Gilles > > > > - > > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > > For additional commands, e-mail: dev-h...@commons.apache.org > > > > - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [all] Binaries for example modules
On Thu, 5 Aug 2021 at 17:23, Gilles Sadowski wrote: > Hi. > > Le jeu. 5 août 2021 à 18:01, Alex Herbert a > écrit : > > > > On Thu, 5 Aug 2021 at 14:07, Gilles Sadowski > wrote: > > > > > Le jeu. 5 août 2021 à 14:08, Gary Gregory a > > > écrit : > > > > > > > > I agree with Matt. > > > > > > Nobody seems to disagree (about not providing convenience *binaries* > > > of the examples). > > > My point was that the examples _must_ be part of the (source) release > > > (with the caveat that they are not subject to BC), in the same way that > > > unit tests are, because they could sometimes exercise the code in a way > > > which the unit tests do not. > > > Maybe I misunderstood Matt's proposal, which I thought was was to not > > > release the examples (i.e. leaving them out of the release branch). > > > > > > > If the release profile in the POM omits the examples modules then they > will > > not be released as binary jars to nexus, and the modules are omitted from > > the site generation. The contents of the distribution release binary > (zip, > > tar.gz) are specified separately. So these can include all the source > text > > files from the examples. > > > > However if the examples modules are not in the POM hierarchy then the > > binaries will not be built from the source as part of the release > process. > > It is possible to include the modules and skip the site generation for > the > > maven-site-plugin. I am not sure about skipping the maven-release-plugin. > > It may be possible using the dryRun parameter but I would have to > > investigate. > > > > If the build of the examples cannot be set-up to be verified during the > > release process then this should be verified by the RM and any reviewers > of > > the release to ensure the examples do build from the source distribution. > > > > In the case of RNG this could involve adding a step to the release guide > to > > state that applications in all the example modules should be run to > ensure > > they compile with the API from the released code. The same can be added > to > > guidelines in the VOTE e-mail. > > > > Would this cover your requirement that the examples code is exercised? > > I do _not_ ask any work to be done in order to complicate the release > process and/or review. > My question was (cf. above and the other thread) whether singling out > the "examples" module has any benefit (apart from saving a few bytes > on Maven Central). > I've just pushed an update to RNG to add more details on how to run the examples. I will look at preparing a release without the examples modules in the next few days. Ideally I would like to ensure the process builds the binaries just to check it is possible but not add them Maven central or the limited module reports to the site. Otherwise I am fine with a manual verification step (that can be scripted) just to build and run each example. The examples are built using Jenkins so they should be kept current and able to compile. Running them is not something done by the CI build. Alex > > Best, > Gilles > > - > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > >
Re: [all] Binaries for example modules
Hi. Le jeu. 5 août 2021 à 18:01, Alex Herbert a écrit : > > On Thu, 5 Aug 2021 at 14:07, Gilles Sadowski wrote: > > > Le jeu. 5 août 2021 à 14:08, Gary Gregory a > > écrit : > > > > > > I agree with Matt. > > > > Nobody seems to disagree (about not providing convenience *binaries* > > of the examples). > > My point was that the examples _must_ be part of the (source) release > > (with the caveat that they are not subject to BC), in the same way that > > unit tests are, because they could sometimes exercise the code in a way > > which the unit tests do not. > > Maybe I misunderstood Matt's proposal, which I thought was was to not > > release the examples (i.e. leaving them out of the release branch). > > > > If the release profile in the POM omits the examples modules then they will > not be released as binary jars to nexus, and the modules are omitted from > the site generation. The contents of the distribution release binary (zip, > tar.gz) are specified separately. So these can include all the source text > files from the examples. > > However if the examples modules are not in the POM hierarchy then the > binaries will not be built from the source as part of the release process. > It is possible to include the modules and skip the site generation for the > maven-site-plugin. I am not sure about skipping the maven-release-plugin. > It may be possible using the dryRun parameter but I would have to > investigate. > > If the build of the examples cannot be set-up to be verified during the > release process then this should be verified by the RM and any reviewers of > the release to ensure the examples do build from the source distribution. > > In the case of RNG this could involve adding a step to the release guide to > state that applications in all the example modules should be run to ensure > they compile with the API from the released code. The same can be added to > guidelines in the VOTE e-mail. > > Would this cover your requirement that the examples code is exercised? I do _not_ ask any work to be done in order to complicate the release process and/or review. My question was (cf. above and the other thread) whether singling out the "examples" module has any benefit (apart from saving a few bytes on Maven Central). Best, Gilles - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [all] Binaries for example modules
On Thu, 5 Aug 2021 at 14:07, Gilles Sadowski wrote: > Le jeu. 5 août 2021 à 14:08, Gary Gregory a > écrit : > > > > I agree with Matt. > > Nobody seems to disagree (about not providing convenience *binaries* > of the examples). > My point was that the examples _must_ be part of the (source) release > (with the caveat that they are not subject to BC), in the same way that > unit tests are, because they could sometimes exercise the code in a way > which the unit tests do not. > Maybe I misunderstood Matt's proposal, which I thought was was to not > release the examples (i.e. leaving them out of the release branch). > If the release profile in the POM omits the examples modules then they will not be released as binary jars to nexus, and the modules are omitted from the site generation. The contents of the distribution release binary (zip, tar.gz) are specified separately. So these can include all the source text files from the examples. However if the examples modules are not in the POM hierarchy then the binaries will not be built from the source as part of the release process. It is possible to include the modules and skip the site generation for the maven-site-plugin. I am not sure about skipping the maven-release-plugin. It may be possible using the dryRun parameter but I would have to investigate. If the build of the examples cannot be set-up to be verified during the release process then this should be verified by the RM and any reviewers of the release to ensure the examples do build from the source distribution. In the case of RNG this could involve adding a step to the release guide to state that applications in all the example modules should be run to ensure they compile with the API from the released code. The same can be added to guidelines in the VOTE e-mail. Would this cover your requirement that the examples code is exercised? Alex
Re: [all] Binaries for example modules
Le jeu. 5 août 2021 à 14:08, Gary Gregory a écrit : > > I agree with Matt. Nobody seems to disagree (about not providing convenience *binaries* of the examples). My point was that the examples _must_ be part of the (source) release (with the caveat that they are not subject to BC), in the same way that unit tests are, because they could sometimes exercise the code in a way which the unit tests do not. Maybe I misunderstood Matt's proposal, which I thought was was to not release the examples (i.e. leaving them out of the release branch). Regards, Gilles P.S. The issue of what should be on the web site and how to do it is independent of the original question. > > Gary > > On Thu, Aug 5, 2021, 07:26 Matt Juntunen wrote: > > > > I think it is preferable to perform the release using only the public API > > > modules. The examples will be released in the source tarball. > > > > +1 > > > > > [...] - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [all] Binaries for example modules
I agree with Matt. Gary On Thu, Aug 5, 2021, 07:26 Matt Juntunen wrote: > > I think it is preferable to perform the release using only the public API > > modules. The examples will be released in the source tarball. > > +1 > > > The question is whether the examples require some additional > advertisement > > on the main website, for example an additional page, or section in the > user guide, to > > describe what examples are available, how to build them locally and why > you > > might want to run them. Otherwise they will just be left as a developer's > > secret hidden in the source release. > > IMO, a section in the user guide listing the example modules available > [1] along with > instructions for building (e.g. what maven profiles to include) would > be sufficient. > > -Matt J > > [1] > https://commons.apache.org/proper/commons-rng/commons-rng-examples/index.html > > On Thu, Aug 5, 2021 at 6:11 AM Alex Herbert > wrote: > > > > On Thu, 5 Aug 2021 at 01:40, Gilles Sadowski > wrote: > > > > > Le jeu. 5 août 2021 à 01:46, sebb a écrit : > > > > > > > > On Wed, 4 Aug 2021 at 13:38, Gilles Sadowski > > > wrote: > > > > > > > > > > Hi. > > > > > > > > > > Le mer. 4 août 2021 à 04:27, Matt Juntunen < > matt.a.juntu...@gmail.com> > > > a écrit : > > > > > > > > > > > > Hello, > > > > > > > > > > > > I apologize if this was resolved already and I missed it, but > did we > > > > > > land anywhere on the issue of whether or not to release binaries > of > > > > > > example code modules? I've included the example module binaries > in > > > > > > previous releases of numbers and geometry but I don't think that > they > > > > > > are actually useful just as binaries. Are we ok to just leave the > > > > > > example modules as code included in the source release? Also, > should > > > > > > they be part of the deployed site or should that just be for the > > > > > > public API portions? > > > > > > > > > > FTR, I quote the question raised in another thread where this issue > > > > > was first mentioned: > > > > > "[...] how can we release (some official version of) the project > as > > > source > > > > > without also releasing the (convenience) binaries for > everything?" > > > > > > > > The ASF releases source. > > > > > > > > Binaries are optional. > > > > > > This has been stated in my quote (cf. "convenience"). > > > The question is whether we want to complexify the release procedure > > > in order to not build the binaries for some of the source. > > > What's the gain for the RM/developers/users? > > > > > > > Looking at the modular project for RNG it may complexify the release > > procedure to not distribute the binary jars for the examples if we still > > wish to report the examples on the site using the modular site structure. > > > > Currently we include all the examples and release using the goals > 'package > > site site:stage deploy'. > > > > If we omit the examples from the module hierarchy then they will not be > > included in the site. The examples will still be included in the source > > release as it creates an archive of everything from the root directory. > > > > However at present the examples in RNG do not have a useful site page. > The > > page simply states a single line description and then a second line > stating > > the module is not part of the public API. See the current examples > overview > > page [1]. Leaving them out of the site would remove the ability to browse > > the source using the module project reports. It would remove the javadoc > > module report. The javadocs are not very informative (see [2]). IMO these > > module reports are not useful and I would drop these entirely from the > site. > > > > The examples in RNG are used for testing functionality. Some of these > > examples create a runnable jar file using the shade plugin to bring in > all > > the dependencies. These are the most useful part of the examples as they > > would allow an end user to run performance tests locally without having > to > > build the program. However the shaded uber-jars have never been released > > and would require some licence checking to be done to see if they can be > > distributed. > > > > I think it is preferable to perform the release using only the public API > > modules. The examples will be released in the source tarball. The > question > > is whether the examples require some additional advertisement on the main > > website, for example an additional page, or section in the user guide, to > > describe what examples are available, how to build them locally and why > you > > might want to run them. Otherwise they will just be left as a developer's > > secret hidden in the source release. > > > > Alex > > > > [1] > > > https://commons.apache.org/proper/commons-rng/commons-rng-examples/index.html > > [2] > > > https://commons.apache.org/proper/commons-rng/commons-rng-examples/commons-rng-examples-stress/apidocs/org/apache/commons/rng/examples/stress/package-summary.html > > > > > > >
Re: [all] Binaries for example modules
On Thu, 5 Aug 2021 at 12:27, Matt Juntunen wrote: > > I think it is preferable to perform the release using only the public API > > modules. The examples will be released in the source tarball. > > +1 > > > The question is whether the examples require some additional > advertisement > > on the main website, for example an additional page, or section in the > user guide, to > > describe what examples are available, how to build them locally and why > you > > might want to run them. Otherwise they will just be left as a developer's > > secret hidden in the source release. > > IMO, a section in the user guide listing the example modules available > [1] along with > instructions for building (e.g. what maven profiles to include) would > be sufficient. > > -Matt J > I previously omitted that RNG has some comprehensive notes for developers in the stress test module written in Markdown [1,2]. There are other software dependencies that must be installed before you can use the stress test application. Thus releasing a binary jar of the RNG part does not lower the barrier to using it very far. Since these are developer tools then keeping the main documentation in the relevant source module is more appropriate. Duplicating this into the user guide may be too technical. An overview section in the user guide would advertise what examples exist. I would prefer that further details be left in the module itself. Since the README.md is generated then perhaps simple steps should be added in a HOWTO.md at the module root. Alex [1] https://github.com/apache/commons-rng/blob/master/commons-rng-examples/examples-stress/endianness.md [2] https://github.com/apache/commons-rng/blob/master/commons-rng-examples/examples-stress/stress_test.md
Re: [all] Binaries for example modules
> I think it is preferable to perform the release using only the public API > modules. The examples will be released in the source tarball. +1 > The question is whether the examples require some additional advertisement > on the main website, for example an additional page, or section in the user > guide, to > describe what examples are available, how to build them locally and why you > might want to run them. Otherwise they will just be left as a developer's > secret hidden in the source release. IMO, a section in the user guide listing the example modules available [1] along with instructions for building (e.g. what maven profiles to include) would be sufficient. -Matt J [1] https://commons.apache.org/proper/commons-rng/commons-rng-examples/index.html On Thu, Aug 5, 2021 at 6:11 AM Alex Herbert wrote: > > On Thu, 5 Aug 2021 at 01:40, Gilles Sadowski wrote: > > > Le jeu. 5 août 2021 à 01:46, sebb a écrit : > > > > > > On Wed, 4 Aug 2021 at 13:38, Gilles Sadowski > > wrote: > > > > > > > > Hi. > > > > > > > > Le mer. 4 août 2021 à 04:27, Matt Juntunen > > a écrit : > > > > > > > > > > Hello, > > > > > > > > > > I apologize if this was resolved already and I missed it, but did we > > > > > land anywhere on the issue of whether or not to release binaries of > > > > > example code modules? I've included the example module binaries in > > > > > previous releases of numbers and geometry but I don't think that they > > > > > are actually useful just as binaries. Are we ok to just leave the > > > > > example modules as code included in the source release? Also, should > > > > > they be part of the deployed site or should that just be for the > > > > > public API portions? > > > > > > > > FTR, I quote the question raised in another thread where this issue > > > > was first mentioned: > > > > "[...] how can we release (some official version of) the project as > > source > > > > without also releasing the (convenience) binaries for everything?" > > > > > > The ASF releases source. > > > > > > Binaries are optional. > > > > This has been stated in my quote (cf. "convenience"). > > The question is whether we want to complexify the release procedure > > in order to not build the binaries for some of the source. > > What's the gain for the RM/developers/users? > > > > Looking at the modular project for RNG it may complexify the release > procedure to not distribute the binary jars for the examples if we still > wish to report the examples on the site using the modular site structure. > > Currently we include all the examples and release using the goals 'package > site site:stage deploy'. > > If we omit the examples from the module hierarchy then they will not be > included in the site. The examples will still be included in the source > release as it creates an archive of everything from the root directory. > > However at present the examples in RNG do not have a useful site page. The > page simply states a single line description and then a second line stating > the module is not part of the public API. See the current examples overview > page [1]. Leaving them out of the site would remove the ability to browse > the source using the module project reports. It would remove the javadoc > module report. The javadocs are not very informative (see [2]). IMO these > module reports are not useful and I would drop these entirely from the site. > > The examples in RNG are used for testing functionality. Some of these > examples create a runnable jar file using the shade plugin to bring in all > the dependencies. These are the most useful part of the examples as they > would allow an end user to run performance tests locally without having to > build the program. However the shaded uber-jars have never been released > and would require some licence checking to be done to see if they can be > distributed. > > I think it is preferable to perform the release using only the public API > modules. The examples will be released in the source tarball. The question > is whether the examples require some additional advertisement on the main > website, for example an additional page, or section in the user guide, to > describe what examples are available, how to build them locally and why you > might want to run them. Otherwise they will just be left as a developer's > secret hidden in the source release. > > Alex > > [1] > https://commons.apache.org/proper/commons-rng/commons-rng-examples/index.html > [2] > https://commons.apache.org/proper/commons-rng/commons-rng-examples/commons-rng-examples-stress/apidocs/org/apache/commons/rng/examples/stress/package-summary.html > > > > > > > - > > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > > For additional commands, e-mail: dev-h...@commons.apache.org > > > > - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additio
Re: [all] Binaries for example modules
On Thu, 5 Aug 2021 at 01:40, Gilles Sadowski wrote: > Le jeu. 5 août 2021 à 01:46, sebb a écrit : > > > > On Wed, 4 Aug 2021 at 13:38, Gilles Sadowski > wrote: > > > > > > Hi. > > > > > > Le mer. 4 août 2021 à 04:27, Matt Juntunen > a écrit : > > > > > > > > Hello, > > > > > > > > I apologize if this was resolved already and I missed it, but did we > > > > land anywhere on the issue of whether or not to release binaries of > > > > example code modules? I've included the example module binaries in > > > > previous releases of numbers and geometry but I don't think that they > > > > are actually useful just as binaries. Are we ok to just leave the > > > > example modules as code included in the source release? Also, should > > > > they be part of the deployed site or should that just be for the > > > > public API portions? > > > > > > FTR, I quote the question raised in another thread where this issue > > > was first mentioned: > > > "[...] how can we release (some official version of) the project as > source > > > without also releasing the (convenience) binaries for everything?" > > > > The ASF releases source. > > > > Binaries are optional. > > This has been stated in my quote (cf. "convenience"). > The question is whether we want to complexify the release procedure > in order to not build the binaries for some of the source. > What's the gain for the RM/developers/users? > Looking at the modular project for RNG it may complexify the release procedure to not distribute the binary jars for the examples if we still wish to report the examples on the site using the modular site structure. Currently we include all the examples and release using the goals 'package site site:stage deploy'. If we omit the examples from the module hierarchy then they will not be included in the site. The examples will still be included in the source release as it creates an archive of everything from the root directory. However at present the examples in RNG do not have a useful site page. The page simply states a single line description and then a second line stating the module is not part of the public API. See the current examples overview page [1]. Leaving them out of the site would remove the ability to browse the source using the module project reports. It would remove the javadoc module report. The javadocs are not very informative (see [2]). IMO these module reports are not useful and I would drop these entirely from the site. The examples in RNG are used for testing functionality. Some of these examples create a runnable jar file using the shade plugin to bring in all the dependencies. These are the most useful part of the examples as they would allow an end user to run performance tests locally without having to build the program. However the shaded uber-jars have never been released and would require some licence checking to be done to see if they can be distributed. I think it is preferable to perform the release using only the public API modules. The examples will be released in the source tarball. The question is whether the examples require some additional advertisement on the main website, for example an additional page, or section in the user guide, to describe what examples are available, how to build them locally and why you might want to run them. Otherwise they will just be left as a developer's secret hidden in the source release. Alex [1] https://commons.apache.org/proper/commons-rng/commons-rng-examples/index.html [2] https://commons.apache.org/proper/commons-rng/commons-rng-examples/commons-rng-examples-stress/apidocs/org/apache/commons/rng/examples/stress/package-summary.html > > - > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > >
Re: [all] Binaries for example modules
Le jeu. 5 août 2021 à 01:46, sebb a écrit : > > On Wed, 4 Aug 2021 at 13:38, Gilles Sadowski wrote: > > > > Hi. > > > > Le mer. 4 août 2021 à 04:27, Matt Juntunen a > > écrit : > > > > > > Hello, > > > > > > I apologize if this was resolved already and I missed it, but did we > > > land anywhere on the issue of whether or not to release binaries of > > > example code modules? I've included the example module binaries in > > > previous releases of numbers and geometry but I don't think that they > > > are actually useful just as binaries. Are we ok to just leave the > > > example modules as code included in the source release? Also, should > > > they be part of the deployed site or should that just be for the > > > public API portions? > > > > FTR, I quote the question raised in another thread where this issue > > was first mentioned: > > "[...] how can we release (some official version of) the project as source > > without also releasing the (convenience) binaries for everything?" > > The ASF releases source. > > Binaries are optional. This has been stated in my quote (cf. "convenience"). The question is whether we want to complexify the release procedure in order to not build the binaries for some of the source. What's the gain for the RM/developers/users? - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [all] Binaries for example modules
On Wed, 4 Aug 2021 at 13:38, Gilles Sadowski wrote: > > Hi. > > Le mer. 4 août 2021 à 04:27, Matt Juntunen a > écrit : > > > > Hello, > > > > I apologize if this was resolved already and I missed it, but did we > > land anywhere on the issue of whether or not to release binaries of > > example code modules? I've included the example module binaries in > > previous releases of numbers and geometry but I don't think that they > > are actually useful just as binaries. Are we ok to just leave the > > example modules as code included in the source release? Also, should > > they be part of the deployed site or should that just be for the > > public API portions? > > FTR, I quote the question raised in another thread where this issue > was first mentioned: > "[...] how can we release (some official version of) the project as source > without also releasing the (convenience) binaries for everything?" The ASF releases source. Binaries are optional. > Gilles > > - > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [all] Binaries for example modules
Hi. Le mer. 4 août 2021 à 04:27, Matt Juntunen a écrit : > > Hello, > > I apologize if this was resolved already and I missed it, but did we > land anywhere on the issue of whether or not to release binaries of > example code modules? I've included the example module binaries in > previous releases of numbers and geometry but I don't think that they > are actually useful just as binaries. Are we ok to just leave the > example modules as code included in the source release? Also, should > they be part of the deployed site or should that just be for the > public API portions? FTR, I quote the question raised in another thread where this issue was first mentioned: "[...] how can we release (some official version of) the project as source without also releasing the (convenience) binaries for everything?" Gilles - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
Re: [all] Binaries for example modules
On Wed, 4 Aug 2021 at 03:27, Matt Juntunen wrote: > > Hello, > > I apologize if this was resolved already and I missed it, but did we > land anywhere on the issue of whether or not to release binaries of > example code modules? I've included the example module binaries in > previous releases of numbers and geometry but I don't think that they > are actually useful just as binaries. Are we ok to just leave the > example modules as code included in the source release? Also, should > they be part of the deployed site or should that just be for the > public API portions? I think that depends on the nature of the examples. NET has several examples which are bundled with the binary release. (They are in a separate jar) The examples vary in functionality, but most are capable of at least rudimentary operation. I think it is important to keep examples out of the main release jars, but it can be useful to include examples as source and binary jars in the binary release bundle (as well as the Javadoc API) so developers have all they need to use the API. [I'm not quite sure why NET includes the main source jar rather than an examples source jar - perhaps that is a mistake.] If the examples are only really useful in the context of the website, then they should probably not be included in releases. > Regards, > Matt J > > - > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
[all] Binaries for example modules
Hello, I apologize if this was resolved already and I missed it, but did we land anywhere on the issue of whether or not to release binaries of example code modules? I've included the example module binaries in previous releases of numbers and geometry but I don't think that they are actually useful just as binaries. Are we ok to just leave the example modules as code included in the source release? Also, should they be part of the deployed site or should that just be for the public API portions? Regards, Matt J - To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
