Rationale

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

|-- 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.vm: add a line in the history of pom.xml for the version being released, 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 its revision number.

Once these modifications are done, you can follow standard component documentation 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 or published.

Then the only difference is with commands to stage the site:

cd target/checkout
mvn -f site-pom.xml site
mvn -f site-pom.xml scm-publish:publish-scm

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 (the link previously added to src/site-docs/index.apt):

...
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:
...