On Thu, 5 Aug 2021 at 12:27, Matt Juntunen <[email protected]> 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
