Multi-Module Maven with github pages

Motivation

The issues

• Project pages are not generated correctly
• Module results are not deployed to maven repository

led to the creation of the example project:

• https://github.com/BITPlan/com.bitplan.multimodule which uses
• https://github.com/BITPlan/com.bitplan.pom for the parent pom definition

in which the github maven site plugin is defined with the configuration

<!-- git hub site plugin https://github.com/github/maven-plugins -->
<plugin>
  <groupId>com.github.github</groupId>
  <artifactId>site-maven-plugin</artifactId>
  <version>${site-maven-plugin.version}</version>
  <configuration>
    <message>Creating site for ${github.owner} ${github.project}
      ${project.version}</message>
    <repositoryName>${github.project}</repositoryName>      <!-- github repo name -->
    <repositoryOwner>${github.owner}</repositoryOwner>    <!-- github username -->
  </configuration>
  <executions>
    <execution>
      <goals>
        <goal>site</goal>
      </goals>
      <phase>site</phase>
    </execution>
  </executions>
</plugin>

Following the suggestion of https://stackoverflow.com/a/19336536/1497139 led to adding

  <distributionManagement>
    <site>
      <id>${project.artifactId}-site</id>
      <url>${project.baseUri}</url>
    </site>
  </distributionManagement>

to the parent pom.xml

mvn clean site 
... wait a long while ...

[INFO] Multi-Module ....................................... SUCCESS [04:22 min]
[INFO] Multi-Module 1 ..................................... SUCCESS [04:09 min]
[INFO] Multi-Module 2 ..................................... SUCCESS [04:09 min]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 12:42 min

and you end up with Module 2 overriding the results of the Multi-Module and Module 1 results

Is it a bug or a feature?

• Its a bug!

Whats the work-around?

1. Do not use the plugin!
2. git clone or pull the gh-pages to a local folder
3. mvn site:stage to a temporary staging directory
4. rsync the results into the git local folder
5. check in the local folder
6. have a cup of coffee or drink a beer / be happy ✓

Do not use the plugin!

1. It's slow (as in really slow ...)
2. It's not reliable (as in 500 HTML Codes)
3. It's not maintained well (as in 57 open issues as of 2018-08
4. It's superflous (see below)
5. Even the committer's don't use it any more (as in a personal mail I got today ..)

git clone or pull the gh-pages to a local folder

 git clone https://github.com/$owner/$project --branch gh-pages --single-branch

mvn site:stage to a temporary staging directory

mkdir -p /tmp/stage/4site
mvn -U clean install site site:stage -DstagingDirectory=/tmp/stage/4site
[INFO] --- maven-site-plugin:3.7.1:stage (default-cli) @ multimodule2 ---
[INFO] Using this base directory for staging: /tmp/stage/4site
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
[INFO]    >>> to file:///tmp/stage/4site/../multimodule2/com.bitplan.multimodule/multimodule2
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] Multi-Module ....................................... SUCCESS [  5.423 s]
[INFO] Multi-Module 1 ..................................... SUCCESS [  4.043 s]
[INFO] Multi-Module 2 ..................................... SUCCESS [  3.393 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 13.665 s

Yes - thats right seconds not minutes!

Experimenting with distributionManagement.url settings

For this we wrote a script to log the results of the mvn site command and analyze where the results go

#!/bin/bash
# WF 2018-08-24

# prepare to log the mvn site command
sitelog=/tmp/sitelog$$.txt

# create an empty staging area
stage=/tmp/stage
rm -rf $stage
mkdir -p $stage/4site

# run the staging of the site against this directory and log the results
mvn -U clean install site site:stage -DstagingDirectory=$stage/4site | tee $sitelog

# what url did we set for the site in distributionManagement?
cat ../com.bitplan.pom/pom.xml | xml2 | grep  /project/distributionManagement/site/url 
# and where did the results go?
egrep "(Pushing|to file)"  $sitelog

${project.baseUri}

/project/distributionManagement/site/url=${project.baseUri}
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/target/site
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/com.bitplan.multimodule
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module1/target/site
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/multimodule-module1/com.bitplan.multimodule/multimodule1
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/multimodule-module2/com.bitplan.multimodule/multimodule2

• the multimodule index file is at /tmp/stage/com.bitplan.multimodule/com.bitplan.multimodule/index.html ✓
• inter-module links work and the main parent module is at /tmp/stage/com.bitplan.pom/index.html ✓

${project.artifactId}

/project/distributionManagement/site/url=${project.artifactId}

• failed: Base URI is not absolute: com.bitplan.pom -> [Help 1]

https://${github.owner}.github.io/${project.artifactId}

/project/distributionManagement/site/url=https://${github.owner}.github.io/${project.artifactId}
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/target/site
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.multimodule/com.bitplan.multimodule
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module1/target/site
[INFO]    >>> to file:///tmp/stage/4site/../multimodule1/com.bitplan.multimodule/multimodule1
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.multimodule/multimodule-module2/target/site
[INFO]    >>> to file:///tmp/stage/4site/../multimodule2/com.bitplan.multimodule/multimodule2

Same result as the working result above ..

• the multimodule index file is at /tmp/stage/com.bitplan.multimodule/com.bitplan.multimodule/index.html ✓
• inter-module links work and the main parent module is at /tmp/stage/com.bitplan.pom/index.html ✓

Test with non -module pom based project

/project/distributionManagement/site/url=https://${github.owner}.github.io/${project.artifactId}
[INFO] Pushing /Users/wf/Documents/workspace/com.bitplan.fritzbox/target/site
[INFO]    >>> to file:///tmp/stage/4site/../com.bitplan.fritzbox/com.bitplan.fritzbox

Example pom.xml files

• https://github.com/kohsuke/pom/blob/master/pom.xml (uses wagon-gitsite ...)
• https://github.com/PathwayCommons/cpath2/blob/master/pom.xml
• https://github.com/CoreMedia/joala/commit/5f12395b8b6d84a39c2c11534ec5a509dace4720

Stackoverflow questions

• https://stackoverflow.com/questions/10848715/multi-module-pom-creating-a-site-that-works
• https://stackoverflow.com/questions/21520904/multi-module-example-of-using-mvn-site-deploy-with-github-pages
  • https://github.com/trajano/app/blob/wagon-git-example/pom.xml
  • https://github.com/khuxtable/wagon-gitsite (2011)
  • https://mvnrepository.com/artifact/com.github.stephenc.wagon/wagon-gitsite (2014-11)

Links

• https://wiki.jenkins.io/display/JENKINS/Site+Creation+and+Deployment

Documentation

• https://maven.apache.org/plugins/maven-site-plugin/
• https://maven.apache.org/plugins/maven-site-plugin/attach-descriptor-mojo.html