svn commit: r1477336 - in /webservices/site/maven/src/site: apt/dev.apt site.xml

[ve...@apache.org]

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>