db-torque-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From tfisc...@apache.org
Subject svn commit: r375032 - /db/torque/site/xdocs/developer-info/site-edit-deploy.xml
Date Sun, 05 Feb 2006 14:37:41 GMT
Author: tfischer
Date: Sun Feb  5 06:37:40 2006
New Revision: 375032

URL: http://svn.apache.org/viewcvs?rev=375032&view=rev
Log:
OOp,s that should have been included in the last commit:
- Removed broken links from the changes.xml
- used absolute links pointing to the old versions in the navigation.xml
- added documentation about the site organsiation

Added:
    db/torque/site/xdocs/developer-info/site-edit-deploy.xml

Added: db/torque/site/xdocs/developer-info/site-edit-deploy.xml
URL: http://svn.apache.org/viewcvs/db/torque/site/xdocs/developer-info/site-edit-deploy.xml?rev=375032&view=auto
==============================================================================
--- db/torque/site/xdocs/developer-info/site-edit-deploy.xml (added)
+++ db/torque/site/xdocs/developer-info/site-edit-deploy.xml Sun Feb  5 06:37:40 2006
@@ -0,0 +1,191 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright 2001-2005 The Apache Software Foundation.
+
+ Licensed 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.
+-->
+
+<document>
+  <properties>
+    <title>Editing and Deploying the Torque site</title>
+    <author email="fischer@seitenbau.de">Thomas Fischer</author>
+  </properties>
+
+  <body>
+   <section name="Introduction">
+     <p>
+       This document is addressed to Torque committers who wish to edit and
+       deploy the Torque site.  If you find anything missing or wrong,
+       please edit this document.  If you find any procedure unsatisfactory,
+       change it and document it here :-).
+     </p>
+   </section>
+   
+   <section name="Organisation of the site's source code">
+     <p>
+       The Torque site consists of a "frame site" and the "sites" of the 
+       various components of Torque (== maven subprojects).  
+       The sites of the components are embedded
+       in the main site (i.e. the user does not see that he has entered 
+       the component's site, as the navigation on the left hand side 
+       looks the same).  In contrast to the subprojects, the "frame site" 
+       has no tags and branches in svn. (This is why you cannot get
+       the frame site from the trunks svn directory).
+     </p>
+     
+     <p>
+       Each subproject keeps its documentation in its own xdocs subdirectory.
+       Currently, the templates subproject does not have its own documentation.
+       There is also a subproject (docs-all-components) which contains
+       documentation which affects mor than one subproject. 
+     </p>
+   </section>
+   
+   <section name="Adding new documentation">
+     <p>
+       If you want to add new documents, please think about where 
+       they should be added:
+       
+       <ul>
+         <li>
+           If they affect only one component of Torque, add them to the xdocs
+           of the component .
+         </li>
+         <li>
+           If they affect more than one component of Torque, and the information
+           possible changes with each release, add them to the
+           docs-all-components subproject site.
+         </li>
+         <li>
+           If the new documents affect Torque as a whole, add them to the
+           site subproject.
+         </li>
+       </ul>
+     </p>
+   </section>
+   
+   <section name="Editing the navigation">
+     <p>
+       As the navigation should look "the same" from the main site and
+       each subproject, changes made to the "frame navigation", i.e. the
+       navigation items which can be seen from every page of the site,
+       must be made in the site subproject and the site of every component
+       alike. 
+       (Probably there is some way to script this, but as this will probably
+       be very different for a Maven 2 build, I do not think it is worth while
+       now.)
+     </p>
+     
+     <p>
+       If the change in the navigation affects a place which can not be seen
+       from everywhere in the project (e.g. a new item in the "references"
+       section of the runtime docs), there is no need to update the 
+       navigation.xml's of the other subprojects and the frame site.
+     </p>
+   </section>
+   
+   <section name="Deploying the site">
+     <p>
+       This is a step-by-step guide to deploy the whole site. 
+       If you only want to deploy the documentation for a subproject,
+       omit the steps to be omitted from the description below.
+       The guide assumes that the necessary ssh properties and maven properties
+       are set.
+       <ul>
+         <li>
+           It might be a good idea to create a tar.gz backup of the current
+           state of the site in your home directory, in case anything goes
+           wrong.
+         </li>
+         <li>
+           Build the sites of the frame site and the components using
+           "maven site" in each project.  This might take a while because of
+           the linkchecking.
+         </li>
+         <li>
+           Deploy the frame site and the components using "maven site:deploy".
+           The frame site will be deployed to the correct place.  The sites
+           of the subprojects will be deployed to 
+           db.apache.org/torque/${subproject-name}, where they are not visible.
+         </li>
+         <li>
+           Move the sites of the subprojects to the correct place, 
+           db.apache.org/torque/releases/torque-${version}/${subproject-name}.
+           (Probably this step can be automated by changing the siteDirectory
+           in the pom, I have not tested this.)
+         </li>
+         <li>
+           Empty the cache of your browser and check everything is ok on
+           <a href="http://db.apache.org/torque/">http://db.apache.org/torque/</a>
+         </li>
+         <li>
+           If you are satisfied with the new site and noone complains during
+           the next few days, delete the backup tar.gz.
+         </li>
+       </ul>
+     </p>
+   </section>
+   
+   <section name="Updating the site for a new release">
+     <p>
+       The following steps are necessary if a new release is created.
+       I have not tested the procedure, so think yourself instead of following
+       blindly (as always :-) )
+       
+       <ul>
+         <li>
+           Create a backup tar.gz of the site AND copy the whole site 
+           to your home directory for the site archive.
+         </li>
+         <li>
+           In the _COPY_ of the site for the archive, remove the previous
+           versions in the releases/ subdirectory.  E.g. if the current version
+           is Torque 3.2 and you want to create the site for the release of 
+           Torque 3.2.1, remove everything except the torque-3.2 subdirectory
+           of the releases directory.
+         </li>
+         <li>
+           Add the old version to the "Previous Releases" section in the
+           navigation.xml of the frame site.  Also, change the release number
+           in all navigation.xml's to the new current release number.
+         </li>
+         <li>
+           Deploy the whole site (see above).
+         </li>
+         <li>
+           Clean the directory of the previous version in the new version of
+           the site (NOT in the copy) (in the above examples, this would be 
+           removing releases/torque-3.2/runtime, releases/torque-3.2/generator
+           and so on.)
+         </li>
+         <li>
+           Now copy the copy of the old site to the freshly cleaned subdirectory
+           of the releases/ directory.  The idea is that the "old"
+           http://db.apache.org/torque.index.html is now available under
+           http://db.apache.org/torque/releases/${old.version}/index.html,
+           and so on.
+         </li>
+         <li>
+           Remove the old dev version (if it exists) from the releases 
+           subdirectoy (in our above eample, this would be 
+           releases/torque-3.2.1-dev).
+         </li>
+         <li>
+           Empty your browser cache and check the results.
+         </li>
+       </ul>
+     </p>
+   </section>
+
+  </body>
+</document>



---------------------------------------------------------------------
To unsubscribe, e-mail: torque-dev-unsubscribe@db.apache.org
For additional commands, e-mail: torque-dev-help@db.apache.org


Mime
View raw message