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>
</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.
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
