Skip to content

RELEASING.md

Latest commit

 

History

History
89 lines (59 loc) · 4.51 KB

RELEASING.md

File metadata and controls

89 lines (59 loc) · 4.51 KB
Raw

Releasing and publishing sites

For maintainers. This is the single reference for both — the per-repository READMEs used to each carry their own version of it, and they had drifted into four mutually inconsistent recipes.

One-time setup

Artifacts go to Maven Central through the Sonatype Central Portal. Add the token to your personal ~/.m2/settings.xml:

<settings>
  <servers>
    <server>
      <id>sonatype-central-portal</id>
      <username><!-- Central Portal token username --></username>
      <password><!-- Central Portal token password --></password>
    </server>
  </servers>
</settings>

Generate the token pair at https://central.sonatype.com/ under your account. It is a token, not your account password.

You also need a published GPG key — releases are signed.

Releasing

Releases are cut with maven-release-plugin from the default branch:

mvn release:prepare
mvn release:perform

release:prepare tags and bumps versions; release:perform builds from the tag and deploys.

There is no manual publish step. maven-release-plugin is configured in the parent with <goals>deploy</goals> and <releaseProfiles>plexus-release</releaseProfiles>, so release:perform activates the plexus-release profile. That profile adds GPG signing, attaches sources and a source-release assembly, and sets njord.enabled=true.

Njord is registered as a build extension and configured with autoPublish=true and publishingType=automatic, so it publishes the deployment to Central itself. njord.enabled is false outside the release profile, so ordinary builds are unaffected.

Releasing needs Maven 3.9.0 or later — the plexus-release profile raises minimalMavenBuildVersion above the 3.6.3 required for a normal build.

Afterwards:

  1. Check the release drafter draft on the GitHub releases page, edit it into shape, and publish it. Release notes live on GitHub releases, not in the repository.
  2. Publish the site, so the Javadoc and dependency reports on the site match what is now on Central. See below.

Publishing the site

Sites are published to each repository's own gh-pages branch and served at https://codehaus-plexus.github.io/<repository>/. The parent POM sets maven-site-plugin to skipDeploy, so the publishing is done by maven-scm-publish-plugin against scm.developerConnection, not by site:deploy.

Most repositories are single-module, and bind scm-publish:publish-scm to the site-deploy phase. For those, the whole command is:

mvn -Preporting clean verify site-deploy

That covers plexus-utils, plexus-xml, plexus-io, plexus-archiver, plexus-interpolation, plexus-classworlds, plexus-testing, plexus-i18n, plexus-resources and plexus-velocity.

Multi-module repositories need staging first, because the site has to be assembled across modules before it is pushed:

mvn -Preporting clean verify site site:stage scm-publish:publish-scm

That covers modello, plexus-compiler, plexus-languages and plexus-interactivity.

plexus-pom is neither, because it never grew the scm-publish execution the other single-module projects have. site-deploy there publishes nothing at all, silently. Name the content directory instead:

mvn -Preporting clean verify site
mvn scm-publish:publish-scm -Dscmpublish.content=target/site

Without scmpublish.content the plugin looks in target/staging, which a single-module build never creates. Run it from a checkout of the release tag, so the site reports the version that is on Central rather than the next snapshot, and add -Dscmpublish.dryRun=true the first time: it prints the additions, updates and deletes it would make, and a delete count anywhere near the size of the site means the content directory is wrong.

The -Preporting profile is what adds the Javadoc, JXR and surefire reports. Without it you publish a site with no API documentation, which is worse than not republishing at all.

Sites are published from a local checkout. There is no workflow for it: publishing puts content live with no review step, and Maven site builds break often enough — doxia, site plugin and JDK interactions — that the person doing it should see the output first.

Snapshot deployment

The shared maven-deploy.yml workflow currently has snapshot publishing disabled (the step is a placeholder that echoes and exits). Don't rely on snapshots being on Central; build locally with mvn install instead.