notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

r1711 - in trunk/central/site/src/docs/depot/tutorials: . versioning

From: mcconnell at BerliOS <mcconnell AT mail.berlios.de>
To: notify-dpml AT lists.ibiblio.org
Subject: r1711 - in trunk/central/site/src/docs/depot/tutorials: . versioning
Date: Sat, 5 Aug 2006 05:45:24 +0200

Author: mcconnell
Date: 2006-08-05 05:45:18 +0200 (Sat, 05 Aug 2006)
New Revision: 1711

Added:
trunk/central/site/src/docs/depot/tutorials/versioning/
trunk/central/site/src/docs/depot/tutorials/versioning/decimal.xml
trunk/central/site/src/docs/depot/tutorials/versioning/index.xml
trunk/central/site/src/docs/depot/tutorials/versioning/mixed.xml
trunk/central/site/src/docs/depot/tutorials/versioning/navigation.xml
trunk/central/site/src/docs/depot/tutorials/versioning/opaque.xml
Removed:
trunk/central/site/src/docs/depot/tutorials/versioned.xml
Modified:
trunk/central/site/src/docs/depot/tutorials/navigation.xml
trunk/central/site/src/docs/depot/tutorials/plugins.xml
Log:
addition of versioning tutorial (taking into account opaque, decimal and
mixed version generation styles)

Modified: trunk/central/site/src/docs/depot/tutorials/navigation.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/navigation.xml 2006-08-03
21:47:01 UTC (rev 1710)
+++ trunk/central/site/src/docs/depot/tutorials/navigation.xml 2006-08-05
03:45:18 UTC (rev 1711)
@@ -38,7 +38,7 @@
<item name="Working with Modules" href="modules.html"/>
<item name="Exporting Modules" href="export.html"/>
<item name="Working with Plugins" href="plugins.html"/>
- <item name="Versioned Builds" href="versioned.html"/>
+ <item name="Versioned Builds" href="versioning/index.html"/>
</menu>

</body>

Modified: trunk/central/site/src/docs/depot/tutorials/plugins.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/plugins.xml 2006-08-03
21:47:01 UTC (rev 1710)
+++ trunk/central/site/src/docs/depot/tutorials/plugins.xml 2006-08-05
03:45:18 UTC (rev 1711)
@@ -162,7 +162,7 @@
remote management, or collection policies. The <a
href="../../metro/tutorials/index.html">
Metro Tutorials</a> takes you into another semantic dimension with
the
introduction of an alternative deployment strategy based on the
Metro Component Model
- whereas <a href="versioned.html">our last tutorial in the Depot
collection</a> wraps-up
+ whereas <a href="versioned/index.html">our last tutorial in the
Depot collection</a> wraps-up
with project versions management techniques.
</p>

Deleted: trunk/central/site/src/docs/depot/tutorials/versioned.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/versioned.xml 2006-08-03
21:47:01 UTC (rev 1710)
+++ trunk/central/site/src/docs/depot/tutorials/versioned.xml 2006-08-05
03:45:18 UTC (rev 1711)
@@ -1,135 +0,0 @@
-<?xml version="1.0" encoding="ISO-8859-1"?>
-
-<document>
- <properties>
- <author email="mcconnell AT osm.net">Stephen McConnell</author>
- <title>Version Builds</title>
- </properties>
-
- <body>
-
- <section name="Versioned Builds">
-
- <subsection name="Tutorial Objective">
-
- <p>
- The objective of this tutorial is to demonstrate the usage of
- the <tt>-version</tt> option when building multiple projects.
- </p>
-
- </subsection>
-
- <subsection name="Executing a versioned build">
-
- <p>
- By default the build system assigns the version identifier of
- <tt>SNAPSHOT</tt>.
- </p>
- <p>
- We can override this using the <tt>-version</tt>
- commandline option. In the following example we are requesting a
listing of
- the in-scope projects together with the version cli option. The
resulting
- list is the list of projects that would be build if we dropped to
list option.
- </p>
-
-<pre>$ build -list -version <font color="darkred">ABC</font>
-
-Selection: [3]
-
- [1] project:org/acme/plugin/clock-api#<font color="blue">ABC</font>
- [2] project:org/acme/plugin/clock-impl<font color="blue">#ABC</font>
- [3] module:org/acme/plugin#<font color="blue">ABC</font>
-
-$</pre>
-
- </subsection>
-
- <subsection name="Adding a Decimal Prefix">
-
- <p>
- A generalized version applies to a complete module is sometimes not
sufficient
- to properly describe the desired results of a multi-p[roject build
in terms of
- version naming requirements. For example, by applying the generic
<tt>-version</tt>
- cli option we are stating that all resources defined withing the
module (without an
- explicit version declaration) shall be produced with version XYZ. A
more realistic
- scenario is that your top-level index versioning strategy could
reflect a public
- XML specification whereas internal project version could reflect API
based version
- evolution. In these scenarios it is useful to include a
specification prefix - for
- example the version identifier "1.0.0-RC3" could be expressed as a
decimal prefix
- of "1.0.0" and a version suffix of "RC3". Depot enables this
strategy through the
- following properties:
- </p>
-
- <table>
- <tr>
- <td>project.version-prefix.enabled</td>
- <td>If true then the version value generated for a given project
- will be derived from the values of the major, minor and
micro
- project version attributes described below.</td>
- </tr>
- <tr>
- <td>project.major.version</td>
- <td>The major version prefix value (must be an integer).</td>
- </tr>
- <tr>
- <td>project.minor.version</td>
- <td>The minor version prefix value (must be an integer).</td>
- </tr>
- <tr>
- <td>project.micro.version</td>
- <td>The minor version prefix value (must be an integer).
Typically
- used to represent a sequential publication value.</td>
- </tr>
- </table>
-
- <p>
- In version prefixing is enabled (typicically via a high-level module
property
- defintion) and major, minor and micro versions are assigned within
respective modules
- and projects (reflecting respective development lifecycles), then
the resulting version
- assigned to a project artifacts will correspond to the the following
convention:
- </p>
-
- <pre>[major].[minor].[micro]-[cli-supplied-version-argument]</pre>
-
- <p>
- The DPML project artifacts use the following convention:
- </p>
-
- <table>
- <tr>
- <td>major</td>
- <td>All resources sharing the same major version are deemed as
backward
- compatible.</td>
- </tr>
- <tr>
- <td>minor</td>
- <td>A minor version represents a functional extension or
enhancement
- that is compatible within the context of the major version
identifier.</td>
- </tr>
- <tr>
- <td>micro</td>
- <td>A micro version represents a sequential release identifier
relative
- to the <tt>[major].[minor]</tt> namespace.</td>
- </tr>
- </table>
-
- </subsection>
-
- <subsection name="Summary">
-
- <p>
- The above sequence demonstrates the impact of the <tt>-version</tt>
option
- in terms of resource naming and the corresponding meta-data (such as
module
- information) that is generated by the build process. All of the
resources
- (jars, module files, etc.) are now suitable for publication into a
public
- (or shared) repository.
- </p>
-
- </subsection>
-
- </section>
-
- </body>
-
-</document>
-

Added: trunk/central/site/src/docs/depot/tutorials/versioning/decimal.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/versioning/decimal.xml
2006-08-03 21:47:01 UTC (rev 1710)
+++ trunk/central/site/src/docs/depot/tutorials/versioning/decimal.xml
2006-08-05 03:45:18 UTC (rev 1711)
@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Version Builds</title>
+ </properties>
+
+ <body>
+
+ <section name="Decimal Versioning Example">
+
+ <subsection name="Assigning major, minor and micro properties">
+
+ <p>
+ Decimal versions are generated relative to the following project
+ defintion properties. All property values must be integers.
+ </p>
+
+ <ul>
+ <li>project.major.version</li>
+ <li>project.minor.version</li>
+ <li>project.micro.version</li>
+ </ul>
+
+ </subsection>
+
+ <subsection name="Using the decimal CLI option">
+
+ <p>
+ Decimal versioning is enabled via the Depot build tool
<tt>-decimal</tt>
+ command-line option. In this example properties from the major,
minor and
+ micro values has been added to the index.xml file (see below).
+ </p>
+
+<pre>$ build -list -decimal
+
+Selection: [3]
+
+ [1] project:org/acme/plugin/clock-api#1.0.0
+ [2] project:org/acme/plugin/clock-impl#1.0.2
+ [3] module:org/acme/plugin#1.0.2
+
+$</pre>
+
+ </subsection>
+
+ <subsection name="index.xml">
+
+ <p>
+ The following <tt>index.xml</tt> is an update from the plugin
tutorial
+ example and includes additional properties dealing with major, minor
+ and micro version values. If undefined - a decimal value defaults
to
+ zero. Values defined at module level establish the default for
+ subsidiary projects.
+ </p>
+
+<pre>
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<index xmlns="link:xsd:dpml/lang/dpml-module#1.0"
+ xmlns:part="link:xsd:dpml/lang/dpml-part#1.0">
+
+ <imports>
+ <import uri="link:module:ant"/>
+ <import uri="link:module:dpml"/>
+ </imports>
+
+ <module name="org/acme/plugin" basedir=".">
+
+ <font color="darkred"><properties>
+ <property name="project.major.version" value="1"/>
+ <property name="project.micro.version" value="2"/>
+ </properties></font>
+
+ <types>
+ <type id="module" version="1.0">
+ </types>
+
+ <project name="clock-api" basedir="api">
+ <font color="darkred"><properties>
+ <property name="project.micro.version" value="0"/>
+ </properties></font>
+ <types>
+ <type id="jar"/>
+ </types>
+ </project>
+
+ <project name="clock-impl" basedir="impl">
+ <types>
+ <type id="jar"/>
+ <part:plugin class="org.acme.impl.SimpleClock">
+ <part:param value="h:mm"/>
+ <part:param class="java.util.Locale" method="getDefault"/>
+ </part:plugin>
+ </types>
+ <dependencies>
+ <runtime>
+ <include key="clock-api"/>
+ </runtime>
+ <test>
+ <include ref="ant/ant-junit"/>
+ <include ref="dpml/transit/dpml-transit-main"/>
+ </test>
+ </dependencies>
+ </project>
+
+ </module>
+
+</index>
+</pre>
+
+ </subsection>
+
+ <subsection name="Technical Note">
+ <p>
+ The DPML project makes extensive use of decimal versioning and
applies the
+ following convention with respect to major, minor and micro version
values:
+ </p>
+
+ <table>
+ <tr>
+ <td>major</td>
+ <td>All resources sharing the same major version are deemed as
backward
+ compatible.</td>
+ </tr>
+ <tr>
+ <td>minor</td>
+ <td>A minor version represents a functional extension or
enhancement
+ that is compatible within the context of the major version
identifier.</td>
+ </tr>
+ <tr>
+ <td>micro</td>
+ <td>A micro version represents a sequential release identifier
relative
+ to the <tt>[major].[minor]</tt> namespace.</td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/depot/tutorials/versioning/index.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/versioning/index.xml
2006-08-03 21:47:01 UTC (rev 1710)
+++ trunk/central/site/src/docs/depot/tutorials/versioning/index.xml
2006-08-05 03:45:18 UTC (rev 1711)
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Version Builds</title>
+ </properties>
+
+ <body>
+
+ <section name="Versioned Builds">
+
+ <subsection name="Tutorial Objective">
+
+ <p>
+ The default version assigned to build artifacts is the constant
+ string <tt>SNAPSHOT</tt>. The purpose of this tutorial is to
+ present the mechanisms available to control default version
+ identifiers and the techniques used in decimal versioning.
+ </p>
+
+ </subsection>
+
+ <subsection name="Version Generation Styles">
+
+ <table>
+ <tr>
+ <td>snapshot</td>
+ <td>Assignes an opaque version identifier equal to the
+ the constant string <tt>SNAPSHOT</tt> (e.g.
+ <tt>acme-clock-SNAPSHOT</tt>). This is
+ the default system behaviour unless modified by a
+ command line option of project property.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="opaque.html">opaque</a></td>
+ <td>Assignes an opaque version identifier equal to
+ argument supplied in conjunction with the <tt>-version</tt>
+ build command-line option. For example the result of
+ declaring the string <tt>DEMO3</tt> as the argument to
+ <tt>-version</tt> would be <tt>acme-clock-DEMO3</tt>.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="decimal.html">decimal</a></td>
+ <td>Assignes an decimal version identifier composed of
+ a sequence of <tt>[major].[minor].[micro]</tt> integer values
+ where each value is resolved from the respective
+ <tt>project.major.version</tt>, <tt>project.minor.version</tt>,
+ and <tt>project.micor.version</tt> properties. For example
+ the result of declaring <tt>2</tt>, <tt>1</tt>, and <tt>0</tt>
+ as the respective values of the major, minor and micro project
+ properties in conjunction with the <tt>-decimal</tt>
+ command line option would be <tt>acme-clock-2.1.0</tt>.
+ </td>
+ </tr>
+ <tr>
+ <td><a href="mixed.html">mixed</a></td>
+ <td>Assignes an decimal version identifier as a prefix followed
+ by the "<tt>-</tt>" character and an opaque identifier.
+ For example the result of declaring major, minor and micro
properties
+ of <tt>2</tt>, <tt>1</tt>, and <tt>0</tt> in a project defintion
in
+ conjunction with the <tt>-decimal</tt> command line option and a
+ <tt>-version</tt> option argument of <tt>RC1</tt> would be
+ <tt>acme-clock-2.1.0-RC1</tt>.
+ </td>
+ </tr>
+ </table>
+
+ </subsection>
+
+ <subsection name="Summary">
+
+ <p>
+ Using any variation of the opaque or decimal version strategies
presented
+ above results in the generation of artifacts with qualtified
identities.
+ While Depot does not ensure that these identities are unique -
developers
+ can leverage the <tt>build -l -consumers</tt> option in order to
establish
+ the implications of changes on consumer projects. Based on this
information,
+ micro, minor and major version values can be managed (although it is
recognized
+ that the overall management of historical published versions versus
current
+ build version information is an topic that could result in new
management tools).
+ </p>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/depot/tutorials/versioning/mixed.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/versioning/mixed.xml
2006-08-03 21:47:01 UTC (rev 1710)
+++ trunk/central/site/src/docs/depot/tutorials/versioning/mixed.xml
2006-08-05 03:45:18 UTC (rev 1711)
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Versioned Builds</title>
+ </properties>
+
+ <body>
+
+ <section name="Mxed Decimal and Opaque Example">
+
+ <subsection name="Using the decimal and version CLI options in
combination">
+
+ <p>
+ Using the decimal switch in combination with a version tag results
in the
+ generation of a version value equivalent to
<tt>[decimal]-[tag]></tt>. The
+ following example demonstrates this relative to the index file used
in the
+ decimal versioning example.
+ </p>
+
+<pre>$ build -list -decimal -version RC1
+
+Selection: [3]
+
+ [1] project:org/acme/plugin/clock-api#1.0.0-RC1
+ [2] project:org/acme/plugin/clock-impl#1.0.2-RC1
+ [3] module:org/acme/plugin#1.0.2-RC1
+
+$</pre>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

Added: trunk/central/site/src/docs/depot/tutorials/versioning/navigation.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/versioning/navigation.xml
2006-08-03 21:47:01 UTC (rev 1710)
+++ trunk/central/site/src/docs/depot/tutorials/versioning/navigation.xml
2006-08-05 03:45:18 UTC (rev 1711)
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+
+<project>
+
+ <title>Versioned Builds</title>
+
+ <body>
+
+ <menu>
+ <item name="Opaque" href="opaque.html"/>
+ <item name="Decimal" href="decimal.html"/>
+ <item name="Mixed" href="mixed.html"/>
+ </menu>
+
+ </body>
+
+</project>

Added: trunk/central/site/src/docs/depot/tutorials/versioning/opaque.xml
===================================================================
--- trunk/central/site/src/docs/depot/tutorials/versioning/opaque.xml
2006-08-03 21:47:01 UTC (rev 1710)
+++ trunk/central/site/src/docs/depot/tutorials/versioning/opaque.xml
2006-08-05 03:45:18 UTC (rev 1711)
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<document>
+ <properties>
+ <author email="mcconnell AT osm.net">Stephen McConnell</author>
+ <title>Opaque Versioning Example</title>
+ </properties>
+
+ <body>
+
+ <section name="Opaque Versioning Example">
+
+ <subsection name="Using the version CLI option">
+
+ <p>
+ We can override the default <tt>SNAPSHOT</tt> version identifier
using the <tt>-version</tt>
+ command-line option. In the following example we are requesting a
listing of
+ the in-scope projects together with the version cli option using the
value <tt>ABC</tt>.
+ </p>
+
+<pre>$ build -list -version <font color="darkred">ABC</font>
+
+Selection: [3]
+
+ [1] project:org/acme/plugin/clock-api#<font color="blue">ABC</font>
+ [2] project:org/acme/plugin/clock-impl<font color="blue">#ABC</font>
+ [3] module:org/acme/plugin#<font color="blue">ABC</font>
+
+$</pre>
+
+ </subsection>
+
+ </section>
+
+ </body>
+
+</document>
+

r1711 - in trunk/central/site/src/docs/depot/tutorials: . versioning, mcconnell at BerliOS, 08/04/2006