Built by Maven

Apache Maven SCM Publish Plugin

The maven-scm-publish-plugin is a utility plugin to allow publishing Maven website to any supported SCM. The primary goal was to have an utility plugin to allow Apache projects to publish Maven websites via the ASF svnpubsub system.

In addition to SCM operations, it takes care to fix newline inconsistencies generated by maven-site-plugin (see MSITE-121), which prevents simple content import to SCM.

The plugin has been tested with Git SCM too and by example can push content for GitHub Pages.

Implementation

The plugin works from staged website by default (see content parameter).

It first checks out the contents of a directory from the SCM (see pubScmUrl parameter) into target/scmpublish-checkout by default (see checkoutDirectory parameter).

Then locally staged content is applied to the check-out, issuing appropriate SCM commands to add and delete entries, followed by a check-in.

The scmpublish.dryRun parameter to the plugin avoids all SCM operations, and simply logs out the added, deleted, and changed files.

The scmpublish.skipCheckin parameter omits the final checkin. This allows you to visit target/scmpublish-checkout, and validate its contents before submitting to the SCM.

Publishing any content to SCM

Even without any pom.xml/Maven project, you can update SCM content with a local content:

mvn scm-publish:publish-scm -Dscmpublish.pubScmUrl=scm:<scm-provider>... -Dscmpublish.content=...path-to-content...

SCM content will be checked-out to a temporary directory, then local content will be applied to the check-out, before it is checked-in back.

See maven.apache.org content import script for an example.

See Some Tips.

Known Limitations

There are 2 known limitations:

  • for Subversion, the plugin can create the initial SCM directory if it does not exist. But for Git by example, if you use a branch, the branch won't be created: you have to create it manually,
  • the plugin works well for multi-module websites publishing to a complete directory: you just need to publish mvn site:stage content. But if one module does not publish its content to the same directory (like Surefire or Enforcer, which have a base directory and one plugin in /plugins/), this staging area can't be simply imported.

Future Dreams

Ideally, scm urls would be supported in <distributionManagement> section of the POM, then publishing would simply be mvn site-deploy, without any problems for non-flat multi-modules sites.

To reach such a dream, there are some steps:

  • fix inconsistent newlines generated by maven-site-plugin (caused by site.vm template and resources taken from skin jar without fixing newlines): MSITE-121 is fixed in maven-site-plugin 3.4,
  • improve wagon-scm to put a whole directory content in one commit, and not with one commit per file.

Then this plugin would be outdated, replaced by natural maven-site-plugin:deploy goal.