How the Web site is built - overview
The Web services project uses the following approach to build a Web site with a consistent look and feel across multiple subprojects:
- The Web services project defines its own parent POM that extends the org.apache:apache super POM. The Maven coordinates of this parent POM are org.apache.ws:ws-parent and the sources are located here: https://svn.apache.org/repos/asf/webservices/parent/. This parent POM is expected to be used by all subprojects and is responsible for several things:
- It deploys a site descriptor with reasonable defaults for the site configuration. This configuration is inherited by all subprojects that use the parent POM. It ensures a minimum of consistency between projects and includes the following settings:
- A Maven skin that is graphically a bit more sophisticated than the default skin (which is really ugly).
- A side bar menu with links required by the Apache Project Branding Requirements.
- Breadcrumbs that ensure consistent navigation between the root site and the sites for the subprojects.
- It contains the necessary configurations to enable usage of the maven-scm-publish-plugin to deploy sites directly to the svnpubsub area in SVN.
- It defines defaults for certain plugins used by the site generation process (such as maven-javadoc-plugin). The goal is to reduce the number of unnecessary file changes that occur when regenerating the site. This should avoid mass changes when committing the new version of the site.
- It defines default Maven metadata that applies to all subprojects, e.g. the mailing lists.
- The root site is generated using a Maven project as well. It is located here: https://svn.apache.org/repos/asf/webservices/site/maven/. The project is configured with maven-scm-publish-plugin so that the root site can be published with a few commands (more on this below).
Obviously, the parent POM requires a separate release, but since it is set up as a Maven project that follows the standard Maven release procedure, that is not so much of an issue. On the other hand, republishing the root site doesn't require a release, and the project version is set to a fixed value (0).
Requirements for subprojects
The Maven setup of each subproject should meet the following minimum requirements:
- The project must inherit the WS parent POM (org.apache.ws:ws-parent). During the release process, the version of the parent POM should be updated to the latest version.
- The root POM of the project must have a site entry in the distributionManagement section that points to the right location in the svnpubsub area: scm:svn:https://svn.apache.org/repos/asf/webservices/website/....
- If the project folder in the svnpubsub area contains files or directories that are not generated by Maven, then the root POM must contain a configuration for the maven-scm-publish-plugin that declares them using the ignorePathsToDelete property (See the POM of the root site for an example).
- The site.xml file for the project must be configured appropriately. In most cases, it should only contain menu entries and inherit everything else from the site descriptor of the WS parent POM. It may also reconfigure the left banner to replace it with the project's logo.
Republishing the site for a subproject
To republish the Maven site of a subproject, start by executing the following commands:
mvn clean site
mvn site:stage scm-publish:publish-scm -Dscmpublish.skipCheckin=true
Then go to the target/scmpublish-checkout directory and check the changes. In particular, you should check that no files or directories have been unexpectedly marked for deletion. I you are satisfied with the result, commit them using svn commit. That's it!
If you know what you are doing, you may omit the scmpublish.skipCheckin property. In this case, publish-scm will commit the changes immediately.
Note that the procedure described above is designed to work both with single module and multi-module Maven builds. Actually, for single module projects, a simpler command could be used.
Republishing the root site
Republishing the root site requires the same sequence of commands as for a subproject. Note that the POM configures the ignorePathsToDelete property of the maven-scm-publish-plugin to avoid deleting directories belonging to subprojects, as well as files such as .htaccess and robots.txt which are not managed by the Maven project. You should therefore always use scmpublish.skipCheckin=true and carefully review the changes before committing them.