Author: veithen
Date: Mon Apr 29 20:55:14 2013
New Revision: 1477336
URL: http://svn.apache.org/r1477336
Log:
Added some documentation about how to build the site (including sites for
subprojects).
Added:
webservices/site/maven/src/site/apt/dev.apt
Modified:
webservices/site/maven/src/site/site.xml
Added: webservices/site/maven/src/site/apt/dev.apt
URL:
http://svn.apache.org/viewvc/webservices/site/maven/src/site/apt/dev.apt?rev=1477336&view=auto
==============================================================================
--- webservices/site/maven/src/site/apt/dev.apt (added)
+++ webservices/site/maven/src/site/apt/dev.apt Mon Apr 29 20:55:14 2013
@@ -0,0 +1,110 @@
+~~ Licensed to the Apache Software Foundation (ASF) under one
+~~ or more contributor license agreements. See the NOTICE file
+~~ distributed with this work for additional information
+~~ regarding copyright ownership. The ASF licenses this file
+~~ to you under the Apache License, Version 2.0 (the
+~~ "License"); you may not use this file except in compliance
+~~ with the License. You may obtain a copy of the License at
+~~
+~~ http://www.apache.org/licenses/LICENSE-2.0
+~~
+~~ Unless required by applicable law or agreed to in writing,
+~~ software distributed under the License is distributed on an
+~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+~~ KIND, either express or implied. See the License for the
+~~ specific language governing permissions and limitations
+~~ under the License.
+
+ ---------------------
+ Developer resources
+ ---------------------
+
+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/}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
+ {{{http://www.apache.org/foundation/marks/pmcs}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
+
{{{http://maven.apache.org/plugins/maven-scm-publish-plugin/}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/}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.
Modified: webservices/site/maven/src/site/site.xml
URL:
http://svn.apache.org/viewvc/webservices/site/maven/src/site/site.xml?rev=1477336&r1=1477335&r2=1477336&view=diff
==============================================================================
--- webservices/site/maven/src/site/site.xml (original)
+++ webservices/site/maven/src/site/site.xml Mon Apr 29 20:55:14 2013
@@ -48,6 +48,7 @@
<menu name="Resources">
<item name="Wiki" href="http://wiki.apache.org/ws/"/>
<item name="IRC" href="irc.html"/>
+ <item name="Developer Resources" href="dev.html"/>
</menu>
</body>
</project>
