Rationale

To be able to publish a documentation for the parent POM without affecting released POM and site.xml, parent POM projects have a specific structure, with the addition of site-pom.xml and src/site-docs provide mvn -f site-pom.xml site:

|-- pom.xml
|-- site-pom.xml
`-- src
    |-- site
    |   `-- site.xml
    `-- site-docs
        |-- apt
        |   `-- index.apt
        `-- site.xml

And the index.apt page not only contains instructions about the content of the parent POM, but it maintains a history of POM releases links and diffs.

Each specific step is done to maintain site-pom.xml and index.apt in sync with the release being released.

Stage the release

Before staging the release with usual procedure, you need to update site-pom.xml and index.apt to take the future release into account:

1. update site-pom.xml parent POM version to match the version being released,
2. update src/site-docs/index.apt: add a line in the history of pom.xml for the future version, referring to the future svn release tag and date. Hint: in the diff link, the value for the r2 parameter is easily found by following the previous version's link and copying revision number.

Once these modifications are done, you can follow standard staging steps taking care to use the site-pom.xml POM, with mvn -f site-pom.xml ... command, each time the parent POM's site is generated.

Staging the latest documentation

Once the release is prepared, but before the release vote, the site needs to be staged.

The parent POMs are configured to stage the documentation in a "versioned" directory such as /pom/XXX-Y.

1. Stage the documentation for the current release version (not the new snapshot).

   cd target/checkout
   mvn -f site-pom.xml site site:stage-deploy

   Note: It requires Maven 2.1.0 or higher to successfully deploy to people.apache.org via SSH. Older Maven versions will fail due to com.jcraft.jsch.JSchException: Algorithm negotiation fail.

   Note: You should verify the deployment of the site on the Maven website (you need to wait the sync).

   http://maven.apache.org/pom/XXX-Y/

2. Verify/change folder permissions to 0775 and files permissions to 0664. Log on to people.apache.org and change to the directory above the staging directory. Then run these commands:

   cd /www/maven.apache.org/pom
   find . -type d -exec chmod a+rx,g+w {} \;
   find . -type f -exec chmod 664 {} \;

Call the vote

In the vote, instead of providing links to JIRA, the parent POMs should include a link to the SVN changes since the last release:

...
Hi,

Changes since the last release:
http://svn.apache.org/viewvc/maven/pom/tags/<TAG>/pom.xml?r1=HEAD&r2=<REVISION-OF-LAST-RELEASE>&diff_format=h

Staging repo:
...

Deploying the release website

After the release has passed, the site needs to be uploaded.

Note: Be sure to generate and deploy the site using the same version of the release. Typically, you need to check out the tag (or go to target/checkout)

cd target/checkout
mvn -f site-pom.xml site-deploy

Note: You can not just copy the documentation from the staging site above into the released documentation as the links are not identical. See the email thread http://www.nabble.com/forum/ViewPost.jtp?post=24018250&framed=y

To review the site, wait for the files to arrive at

http://maven.apache.org/pom/XXX/

The wait is necessary to allow the site to be rsync'ed into production.

Updating the Maven site

Check out the Maven site project from https://svn.apache.org/repos/asf/maven/site/trunk or pull the latest changes if already checked out.

Update the version number and release date for the parent POM on the src/site/apt/pom/index.apt page.

Commit your changes and then deploy the site.

mvn clean site-deploy