On Wed, 13 Nov 2019 at 14:02, Alex Herbert <alex.d.herb...@gmail.com> wrote:
> > On 13/11/2019 13:49, sebb wrote: > > +1 for CP > > > > CP versions are entirely optional; a new version is only used if a > > component chooses to use it. > > > > Is this also true of commons-skin? > > If so, then +1 > > cp bundles this site descriptor: > > src/site.xml > > which contains: > > <skin> > <groupId>org.apache.commons</groupId> > <artifactId>commons-skin</artifactId> > <version>4.1</version> > Might make sense to use a property for the version. > </skin> > > So the skin is specified by cp. > > You can only have 1 skin tag in a site descriptor. > > I did a quick test to use a <skin> tag in the site descriptor for RNG. > This overrides the one in commons parent. > > So cp could be updated without updating the skin. > > I could update the skin and release it for use with RNG. Other > components could opt in to a change of the skin using their site > descriptor. When stability is known then cp could be updated for the skin. > > Thanks for checking. I am +1 on proceeding as you suggest. > Alex > > > > > If not, then extra care needs to be taken to ensure backwards > compatibilty. > > There should probably be a formal vote on the actual changes in that > case. > > > > > > On Wed, 13 Nov 2019 at 13:32, Alex Herbert <alex.d.herb...@gmail.com> > wrote: > > > >> The recent release of RNG has highlighted some issues with the commons > >> parent configuration for multi-module builds and a desirable change to > >> commons skin. > >> > >> 1. [parent] JaCoCo aggregate reports are included. > >> > >> Aggregate reports show coverage of dependencies. Since most commons > >> components are stand-alone this should be disabled and the report set > >> updated to have non-aggregate reports. > >> > >> An example of the output is shown for the recently release BCEL: > >> > >> https://commons.apache.org/proper/commons-bcel/project-reports.html > >> > >> The aggregate report is empty. > >> > >> > >> 2. [parent] japicmp does not allow clean opt-in > >> > >> The japicmp maven plugin is immature. If set to skip the report it still > >> creates a menu entry in the site reports page. See this release of > >> Collections: > >> > >> > https://commons.apache.org/proper/commons-collections/project-reports.html > >> > >> The link for the japicmp report is a blank page. > >> > >> > >> For collections this could be fixed by running the report. > >> > >> For a multi-module build using japicmp any module with no code (i.e. a > >> pom) has this empty entry if japicmp is enabled as the skip > >> functionality does not work. > >> > >> > >> The solution is to move the reporting section from the main > >> configuration into the japicmp profile. This allows opt-in on a > >> per-module basis to japicmp. > >> > >> > >> 3. [skin] Customisation of the site <head> section > >> > >> RNG uses formulas in the site documentation. Ideally this would be > >> rendered latex using MathJax [1]. > >> > >> This cannot be included in the site descriptor for the project as the > >> <head> entry for each page is generated by commons-skin. This adds > >> javascript to allow pretty print of code inside <pre "prettyprint"> > >> tags. I would like to add a javascript tag to allow inclusion of > MathJax. > >> > >> > >> I have rendered the RNG site using these changes and staged it here: > >> > >> mvn package site site:stage -Dcommons.release.version=1.2 > >> -DcomparisonVersion=1.2 > >> > >> https://home.apache.org/~aherbert/commons-rng-1.4-site/index.html > >> > >> > >> Top level reports page does not have japicmp: > >> > >> > https://home.apache.org/~aherbert/commons-rng-1.4-site/project-reports.html > >> > >> Components do: > >> > >> > >> > https://home.apache.org/~aherbert/commons-rng-1.4-site/commons-rng-simple/project-reports.html > >> > >> (There are also no jacoco aggregate reports.) > >> > >> > >> You can view how MathJax is rendered on this page: > >> > >> https://home.apache.org/~aherbert/commons-rng-1.4-site/developers.html > >> > >> (search for 'will render an in-line formula') > >> > >> > >> AFAIK an update to commons-skin to include MathJax will not effect sites > >> that do not contain the \( or \[ characters in plain text on site pages. > >> > >> > >> I propose to: > >> > >> - Update commons-skin to add a MathJax script to the <head> section > >> > >> - Release commons-skin (last release was May 2015) > >> > >> - Update commons-parent: > >> > >> - Use the new commons-skin > >> - Remove JaCoCo aggregate reports > >> - Reconfigure japicmp for clean opt-in > >> > >> > >> Alex > >> > >> > >> [1] https://www.mathjax.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 > >
