[All] Exclude a module from released binaries (Was: Issue in POM [...])

[Gilles Sadowski <gi...@gmail.com>]

Hi.

Le mer. 21 juil. 2021 à 05:09, Matt Juntunen
<ma...@gmail.com> a écrit :
>
> Even though I've included the example module binaries in releases for
> commons-numbers and commons-geometry, I would vote that we only
> include them in source form in the future.

Well the question is whether *this* is an acceptable option for a
"Commons" component.
Currently: Whatever is officially released (i.e. as source) is also
provided as (convenience) binaries.

IIUC departing from that needs a *vote*.
[What we can readily do is (entirely) exclude a module from the
release (as was done for [Numbers] v1.0).]
If the rest of the message is not convincing, feel free to start a
[Vote] thread.

PersonalIy I don't mind either way, but I'm not sure that special
handling of the "examples" is worth the trouble.

> For these particular
> projects, they do not seem to be worthwhile to have as binaries.

Well, the benchmarks are in the "examples" module, and for one
thing, it would be nice if they can be run without maven installed
(I don't know whether it already works).

The rest are usually toy applications but they are also meant as
a "Get Started" user guide; having them part of the release ensures
that they are up-to-date.

Also the "examples" module sometimes contain non-trivial applications
(see e.g. [RNG] thanks to Alex), and having some component exclude
it while others don't will be a potential source of confusion (for the RM
and the reviewers).

> I have not looked at the commons-math examples, though.

Those that illustrate usage of the "neuralnet" codes are some kind of
validation tests; without them, unit tests are not sufficient to demonstrate
that the code works as expected (cf. the relatively low coverage).

Regards,
Gilles

>>> [....]

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

Re: [All] Exclude a module from released binaries (Was: Issue in POM [...])

[Gilles Sadowski <gi...@gmail.com>]

Le mer. 21 juil. 2021 à 16:27, Alex Herbert <al...@gmail.com> a écrit :
>
> On Wed, 21 Jul 2021 at 13:16, Gary Gregory <ga...@gmail.com> wrote:
>
> > FWIW, Commons VFS does not publish its Sandox module.
> >
> > One reason to not publish a binaray version of a module is to lessen the
> > chance of complaints of breaking changes. This might not happen for
> > examples but you never know what people do with code we put out there.
> >
>
> In [RNG] the examples are not subject to binary compatibility checks. So if
> we continue to release them then there is no guarantee of BC.

Same for all the math-related components.

> >
> > Gary
> >
> > On Wed, Jul 21, 2021, 08:06 Gilles Sadowski <gi...@gmail.com> wrote:
> >
> > > Hi.
> > >
> > > Le mer. 21 juil. 2021 à 05:09, Matt Juntunen
> > > <ma...@gmail.com> a écrit :
> > > >
> > > > Even though I've included the example module binaries in releases for
> > > > commons-numbers and commons-geometry, I would vote that we only
> > > > include them in source form in the future.
> > >
> > > Well the question is whether *this* is an acceptable option for a
> > > "Commons" component.
> > > Currently: Whatever is officially released (i.e. as source) is also
> > > provided as (convenience) binaries.
> > >
> > > IIUC departing from that needs a *vote*.
> > > [What we can readily do is (entirely) exclude a module from the
> > > release (as was done for [Numbers] v1.0).]
> > > If the rest of the message is not convincing, feel free to start a
> > > [Vote] thread.
> > >
> > > PersonalIy I don't mind either way, but I'm not sure that special
> > > handling of the "examples" is worth the trouble.
> > >
> > > > For these particular
> > > > projects, they do not seem to be worthwhile to have as binaries.
> > >
> > > Well, the benchmarks are in the "examples" module, and for one
> > > thing, it would be nice if they can be run without maven installed
> > > (I don't know whether it already works).
> > >
> > > The rest are usually toy applications but they are also meant as
> > > a "Get Started" user guide; having them part of the release ensures
> > > that they are up-to-date.
> > >
> > > Also the "examples" module sometimes contain non-trivial applications
> > > (see e.g. [RNG] thanks to Alex), and having some component exclude
> > > it while others don't will be a potential source of confusion (for the RM
> > > and the reviewers).
> >
>
> In [RNG] the examples are released but as jar files that contain only the
> classes in the examples module. We have not released the shaded jar file
> that allows you to run the example applications using only a JVM and the
> single uber jar. To run them you would have to put all the dependencies on
> the class path.
>
> There is documentation in the examples module that shows you how to build
> the uber jar and how to run it. I think this should be the way forward with
> example applications.

+1

> I do not have an issue with releasing the source and
> class files of the examples, aside from the caveat that no BC check is
> made. But if these are just the example classes then they cannot be run as
> a program without extra dependencies. I think that releasing a standalone
> uber jar to run a program may be helpful but so far we have not done it.

Given that all JAR files can be easily downloaded from the ASF mirrors,
simply documenting command-line usage should be fine.

> Licences of all the dependencies would have to be checked before doing this.
>
> I am more inclined to favour the option of the examples as being extended
> documentation on the particular release. They can be referenced in the
> documentation for the project and CI builds should ensure they compile to
> keep them current. Adding tests to run the command line programs to
> exercise all the functionality is a lot of work and I would not recommend
> it.

Sure, the additional utilities should not entail additional burden for us.

> The jars can be released just so they can be included as a
> dependency for a reference of the state at the time of the release.
>
>
> > >
> > > > I have not looked at the commons-math examples, though.
> > >
> > > Those that illustrate usage of the "neuralnet" codes are some kind of
> > > validation tests; without them, unit tests are not sufficient to
> > > demonstrate
> > > that the code works as expected (cf. the relatively low coverage).
> >
>
> This sounds like an integration test.

Indeed, they need to combine several classes (thus not a "unit" test).

> Can the current example that is run
> as a command-line application be invoked with the various parameters and
> the output tested that it appears as expected?

I suppose it could; but the toy applications are not worth the trouble.
For the "Traveling Salesman Problem" example, the output is less
interesting (the "problem" is hard-coded) than the source displaying
concurrent usage of the classes.

Regards,
Gilles

>>> [....]

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

Re: [All] Exclude a module from released binaries (Was: Issue in POM [...])

[Alex Herbert <al...@gmail.com>]

On Wed, 21 Jul 2021 at 13:16, Gary Gregory <ga...@gmail.com> wrote:

> FWIW, Commons VFS does not publish its Sandox module.
>
> One reason to not publish a binaray version of a module is to lessen the
> chance of complaints of breaking changes. This might not happen for
> examples but you never know what people do with code we put out there.
>

In [RNG] the examples are not subject to binary compatibility checks. So if
we continue to release them then there is no guarantee of BC.


>
> Gary
>
> On Wed, Jul 21, 2021, 08:06 Gilles Sadowski <gi...@gmail.com> wrote:
>
> > Hi.
> >
> > Le mer. 21 juil. 2021 à 05:09, Matt Juntunen
> > <ma...@gmail.com> a écrit :
> > >
> > > Even though I've included the example module binaries in releases for
> > > commons-numbers and commons-geometry, I would vote that we only
> > > include them in source form in the future.
> >
> > Well the question is whether *this* is an acceptable option for a
> > "Commons" component.
> > Currently: Whatever is officially released (i.e. as source) is also
> > provided as (convenience) binaries.
> >
> > IIUC departing from that needs a *vote*.
> > [What we can readily do is (entirely) exclude a module from the
> > release (as was done for [Numbers] v1.0).]
> > If the rest of the message is not convincing, feel free to start a
> > [Vote] thread.
> >
> > PersonalIy I don't mind either way, but I'm not sure that special
> > handling of the "examples" is worth the trouble.
> >
> > > For these particular
> > > projects, they do not seem to be worthwhile to have as binaries.
> >
> > Well, the benchmarks are in the "examples" module, and for one
> > thing, it would be nice if they can be run without maven installed
> > (I don't know whether it already works).
> >
> > The rest are usually toy applications but they are also meant as
> > a "Get Started" user guide; having them part of the release ensures
> > that they are up-to-date.
> >
> > Also the "examples" module sometimes contain non-trivial applications
> > (see e.g. [RNG] thanks to Alex), and having some component exclude
> > it while others don't will be a potential source of confusion (for the RM
> > and the reviewers).
>

In [RNG] the examples are released but as jar files that contain only the
classes in the examples module. We have not released the shaded jar file
that allows you to run the example applications using only a JVM and the
single uber jar. To run them you would have to put all the dependencies on
the class path.

There is documentation in the examples module that shows you how to build
the uber jar and how to run it. I think this should be the way forward with
example applications. I do not have an issue with releasing the source and
class files of the examples, aside from the caveat that no BC check is
made. But if these are just the example classes then they cannot be run as
a program without extra dependencies. I think that releasing a standalone
uber jar to run a program may be helpful but so far we have not done it.
Licences of all the dependencies would have to be checked before doing this.

I am more inclined to favour the option of the examples as being extended
documentation on the particular release. They can be referenced in the
documentation for the project and CI builds should ensure they compile to
keep them current. Adding tests to run the command line programs to
exercise all the functionality is a lot of work and I would not recommend
it. The jars can be released just so they can be included as a
dependency for a reference of the state at the time of the release.


> >
> > > I have not looked at the commons-math examples, though.
> >
> > Those that illustrate usage of the "neuralnet" codes are some kind of
> > validation tests; without them, unit tests are not sufficient to
> > demonstrate
> > that the code works as expected (cf. the relatively low coverage).
>

This sounds like an integration test. Can the current example that is run
as a command-line application be invoked with the various parameters and
the output tested that it appears as expected?


> >
> > Regards,
> > Gilles
> >
> > >>> [....]
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
> >
>

Re: [All] Exclude a module from released binaries (Was: Issue in POM [...])

[Gary Gregory <ga...@gmail.com>]

FWIW, Commons VFS does not publish its Sandox module.

One reason to not publish a binaray version of a module is to lessen the
chance of complaints of breaking changes. This might not happen for
examples but you never know what people do with code we put out there.

Gary

On Wed, Jul 21, 2021, 08:06 Gilles Sadowski <gi...@gmail.com> wrote:

> Hi.
>
> Le mer. 21 juil. 2021 à 05:09, Matt Juntunen
> <ma...@gmail.com> a écrit :
> >
> > Even though I've included the example module binaries in releases for
> > commons-numbers and commons-geometry, I would vote that we only
> > include them in source form in the future.
>
> Well the question is whether *this* is an acceptable option for a
> "Commons" component.
> Currently: Whatever is officially released (i.e. as source) is also
> provided as (convenience) binaries.
>
> IIUC departing from that needs a *vote*.
> [What we can readily do is (entirely) exclude a module from the
> release (as was done for [Numbers] v1.0).]
> If the rest of the message is not convincing, feel free to start a
> [Vote] thread.
>
> PersonalIy I don't mind either way, but I'm not sure that special
> handling of the "examples" is worth the trouble.
>
> > For these particular
> > projects, they do not seem to be worthwhile to have as binaries.
>
> Well, the benchmarks are in the "examples" module, and for one
> thing, it would be nice if they can be run without maven installed
> (I don't know whether it already works).
>
> The rest are usually toy applications but they are also meant as
> a "Get Started" user guide; having them part of the release ensures
> that they are up-to-date.
>
> Also the "examples" module sometimes contain non-trivial applications
> (see e.g. [RNG] thanks to Alex), and having some component exclude
> it while others don't will be a potential source of confusion (for the RM
> and the reviewers).
>
> > I have not looked at the commons-math examples, though.
>
> Those that illustrate usage of the "neuralnet" codes are some kind of
> validation tests; without them, unit tests are not sufficient to
> demonstrate
> that the code works as expected (cf. the relatively low coverage).
>
> Regards,
> Gilles
>
> >>> [....]
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>