You are viewing a plain text version of this content. The canonical link for it is here.
Posted to torque-dev@db.apache.org by tf...@apache.org on 2006/02/05 15:37:41 UTC
svn commit: r375032 -
/db/torque/site/xdocs/developer-info/site-edit-deploy.xml
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