check of pom.xml to be compliant with mvn site command for github pages

When trying to publish my open source projects to gh-pages with

mvn site

there have been lots of obstacles recently due to changes in the way maven and github pages works.

After studying

Here are some of the needed prerequisites i found and issues i ran into:

prerequisites

git branch needs to show a gh-pages branch e.g. after using the commands in https://gist.github.com/ramnathv/2227408
the version of the maven-site-plugin and the maven-project-info-reports-plugin have to be correct and correctly configured: maven-site plugins 3.3 java.lang.ClassNotFoundException: org.apache.maven.doxia.siterenderer.DocumentContent
dependency.locations.enabled property needs to be false Why am I getting Maven error: "Unable to determine if resource X exists in http://maven.glassfish.org/content/groups/glassfish"?

issues

not even mentioning work arounds i have to use for ssh-wagon and Java8 javadoc and others

The plugins used are IMHO a "moving target". Something that worked a few months ago in my experience will not work today. So I keep fixing my pom.xml files to keep up and the files grow longer and longer.

See e.g. https://github.com/BITPlan/com.bitplan.simplerest/blob/master/pom.xml

For my internal projects I use a parent pom to make sure that the projects have a common configuration. For the open source projects I did not find a way to use a parent pom for a group of projects yet.

I would like to make sure that a working configuration that i found is "transferred" to other configurations. I am thinking e.g. of

a script that might check the configuration
some kind of inheritance mechanism like the parent pom

I assume this is a pretty common problem and there are experiences by SO users on how to tackle this issue accross different project.

What would be a good approach and what tools would be useful?

parent pom with pom packaging What is "pom" packaging in maven? mostly states the use of pom packaging for multi-module projects but it looks it could be used to have a reference for a parent pom. The parentPath defaults to .. see Maven: Non-resolvable parent POM. The overriding of configurations is explained in Maven : Is it possible to override the configuration of a plugin already defined for a profile in a parent POM

Examples for moving targets

Java8 silly javadoc settings
- Maven is not working in Java 8 when Javadoc tags are incomplete
- How to disable Javadoc warnings in Maven Javadoc Plugin?

Solution

As suggested by khmarbaise there is now a common parent pom in place.

mvn site

can be run for all projects using this parent pom with a common set of reports and the result will be transmitted to the corresponding github pages.

A projects specific pom can now be as short as just 25 lines

I am now actually in the process of creating a check script for the pom files and a generate script for the README.md files. This is one of the useful snippets:

usage example:

checkghpages https://github.com/BITPlan com.bitplan.simplerest

Check that the gh-pages exist and create after asking

#
# check the github pages for the given project
# 
# param 1: base url in github
# param 2: project name/directory
#
checkghpages() {
  local l_baseurl="$1"
  local l_project="$2"
  cd $ws/$l_project
  git ls-remote --heads | grep gh-pages > /dev/null
  if [ $? -ne 0 ]
  then
    color_msg $red "github pages branch gh-pages missing for $l_project"
    color_msg $blue "shall i create the branch gh-pages for $l_project?"
    read answer
    case $answer in
      y|Y|yes|Yes|j|Ja) 
        color_msg $blue "creating gh-pages branch for $l_project ..."
        cd /tmp
        # https://gist.github.com/ramnathv/2227408
        git clone $l_baseurl/$l_project
        cd $l_project
        git symbolic-ref HEAD refs/heads/gh-pages
        rm .git/index
        git clean -fdx
        echo "<a href='$l_baseurl/$l_project'>Initial GitHub Page for $l_project</a>" > index.html
        git add .
        git commit -a -m "First pages commit by checkos script"
        git push origin gh-pages
        cd $ws/$l_project
        git pull
      ;;
    esac
  else
    color_msg $green "github pages branch gh-pages for $l_project exists✓"
  fi
}