You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@aries.apache.org by zo...@apache.org on 2011/03/16 11:13:33 UTC
svn commit: r787039 - in /websites/production/aries: ./
content/development/releasingaries.html
content/development/versionpolicy.html
Author: zoe
Date: Wed Mar 16 10:13:33 2011
New Revision: 787039
Log:
Publishing merge to aries site by zoe
Modified:
websites/production/aries/ (props changed)
websites/production/aries/content/development/releasingaries.html
websites/production/aries/content/development/versionpolicy.html
Propchange: websites/production/aries/
------------------------------------------------------------------------------
--- svn:mergeinfo (original)
+++ svn:mergeinfo Wed Mar 16 10:13:33 2011
@@ -1 +1 @@
-/websites/staging/aries/trunk:782169-787009
+/websites/staging/aries/trunk:782169-787037
Modified: websites/production/aries/content/development/releasingaries.html
==============================================================================
--- websites/production/aries/content/development/releasingaries.html (original)
+++ websites/production/aries/content/development/releasingaries.html Wed Mar 16 10:13:33 2011
@@ -236,7 +236,7 @@
<td height="100%" width="100%">
<!-- Content -->
<div class="wiki-content"><p><a name="ReleasingAries-HowtodoanAriesRelease"></a></p>
-<h1 id="how_to_do_an_aries_release">How to do an Aries Release</h1>
+<h1 id="how_to_do_an_aries_release_-_draft_release_by_bundle_process">How to do an Aries Release - Draft release by bundle process</h1>
<p>To create a release you will need to create the release artifacts and move
then to various places (ultimately the Maven central repository). The Maven
commands and general outline of the process looks like this:</p>
@@ -255,11 +255,10 @@ when it has.</p>
<li>Discussion of the release and its content on the aries-dev mailing list.</li>
<li>Creating and storing GPG keys</li>
<li>Setting up your environment</li>
-<li>Creating a branch to release from</li>
<li>JIRA preparation</li>
+<li>Checking the release version of the bundle</li>
<li>Checking release artifacts on your local system</li>
-<li>Creating a snapshot release (optional - not really part of the release
-process, uses mvn deploy)</li>
+<li>Creating a snapshot release </li>
<li>Releasing to a staging repository (uses mvn release:prepare and mvn
release:perform)</li>
<li>Running a vote</li>
@@ -287,14 +286,10 @@ instructions in the file) and checkin</p
<p>Follow the general instructions linked to above. </p>
<p><a name="ReleasingAries-Creatingabranchtoreleasefrom"></a></p>
<h3 id="creating_a_branch_to_release_from">Creating a branch to release from</h3>
-<p>Although this isn't strictly speaking a necessary step it's pretty useful
-to do it. Running the commands to create the release can take some time,
-especially if you have to revert anything. This is much easier if you are
-working in your own branch and not in trunk where other people may be
-committing code.</p>
+<p>The recommendation is to avoid this unless you absolutely have to. </p>
<div class="codehilite"><pre><span class="n">svn</span> <span class="n">copy</span> <span class="n">https:</span><span class="sr">//s</span><span class="n">vn</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">org</span><span class="sr">/repos/</span><span class="n">asf</span><span class="sr">/aries/</span><span class="n">trunk</span> <span class="o">\</span>
-<span class="n">https:</span><span class="sr">//s</span><span class="n">vn</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">org</span><span class="sr">/repos/</span><span class="n">asf</span><span class="sr">/aries/</span><span class="n">branches</span><span class="o">/</span><span class="mi">0</span><span class="o">.</span><span class="n">X</span><span class="o">-</span><span class="n">incubating</span><span class="o">-</span><span class="n">RCx</span> <span class="o">\</span>
+<span class="n">https:</span><span class="sr">//s</span><span class="n">vn</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">org</span><span class="sr">/repos/</span><span class="n">asf</span><span class="sr">/aries/</span><span class="n">branches</span><span class="o">/</span><span class="mi">0</span><span class="o">.</span><span class="n">X</span><span class="o">-</span><span class="n">RCx</span> <span class="o">\</span>
<span class="o">-</span><span class="n">m</span> <span class="s">"Creating a release branch of /aries/trunk."</span>
</pre></div>
@@ -302,7 +297,7 @@ committing code.</p>
<p>Where '0.X' is the number of the release.</p>
<p>Checkout the new branch, for example, for the 0.2-incubating release:</p>
-<div class="codehilite"><pre><span class="n">svn</span> <span class="n">co</span> <span class="n">https:</span><span class="sr">//s</span><span class="n">vn</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">org</span><span class="sr">/repos/</span><span class="n">asf</span><span class="sr">/aries/</span><span class="n">branches</span><span class="o">/</span><span class="mf">0.2</span><span class="o">-</span><span class="n">incubating</span><span class="o">-</span><span class="n">RCx</span> <span class="n">aries</span><span class="o">-</span><span class="mf">0.2</span><span class="o">-</span><span class="n">candidate</span>
+<div class="codehilite"><pre><span class="n">svn</span> <span class="n">co</span> <span class="n">https:</span><span class="sr">//s</span><span class="n">vn</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">org</span><span class="sr">/repos/</span><span class="n">asf</span><span class="sr">/aries/</span><span class="n">branches</span><span class="o">/</span><span class="mf">0.2</span><span class="o">-</span><span class="n">RCx</span> <span class="n">aries</span><span class="o">-</span><span class="mf">0.2</span><span class="o">-</span><span class="n">candidate</span>
</pre></div>
@@ -323,9 +318,19 @@ will not create a staging repository and
repository :-/.</p>
<p>After taking the branch, change the pom versions in trunk to, say,
0.3-incubating or whatever you want to call the next development version.</p>
+<p><a name="ReleasingAries-Checkingbundleversion"></a></p>
+<h3 id="checking_which_version_of_the_bundle_to_release">Checking which version of the bundle to release</h3>
+<p>If the Maven version of the bundle ends -SNAPSHOT then some change has been made which may require a release.
+To get a summary of the changes, use svn to compare with the most recently released tag,
+for example:</p>
+<div class="codehilite"><pre> <span class="n">svn</span> <span class="n">diff</span> <span class="n">https:</span><span class="sr">//s</span><span class="n">vn</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">org</span><span class="sr">/repos/</span><span class="n">asf</span><span class="sr">/aries/</span><span class="n">tags</span><span class="sr">/testsupport-0.3/</span> <span class="n">https:</span><span class="sr">//s</span><span class="n">vn</span><span class="o">.</span><span class="n">apache</span><span class="o">.</span><span class="n">org</span><span class="sr">/repos/</span><span class="n">asf</span><span class="sr">/aries/</span><span class="n">trunk</span><span class="sr">/testsupport/</span> <span class="o">--</span><span class="n">summarize</span>
+</pre></div>
+
+
+<p>In general, if no Java files have changed there is nothing to release (??? check this).</p>
<p><a name="ReleasingAries-Checkingreleaseartifacts"></a></p>
<h3 id="checking_release_artifacts">Checking release artifacts</h3>
-<p>I recommend deleting everything under ...org/apache/aries in your local
+<p>Delete everything under ...org/apache/aries in your local
Maven repo. For linux/Mac users you will find this under ~/.m2/repository/.</p>
<p>Check that the code builds using the usual <a href="buildingaries.html">sequence</a>
of commands, but add the following arguments to the 'mvn install' command:</p>
@@ -344,7 +349,7 @@ Maven repo. For linux/Mac users you will
<p>This will run through the project and its sub projects generating a file
called rat.txt in each target directory.
The 'fn' means it will carry on even if it find a failure. To inspect the
-failures, the easiest way I've found so far is:</p>
+failures, use:</p>
<div class="codehilite"><pre><span class="n">find</span> <span class="o">.</span> <span class="o">-</span><span class="n">name</span> <span class="n">rat</span><span class="o">.</span><span class="n">txt</span> <span class="o">|</span> <span class="n">xargs</span> <span class="nb">grep</span> <span class="o">\!\</span><span class="p">?</span><span class="o">\</span><span class="p">?</span>
</pre></div>
@@ -354,8 +359,8 @@ do not require an Apache license, eg MAN
file does need one. As an alternative you can use 'mvn -Prat install'.</p>
<p><a name="ReleasingAries-Creatingasnapshotrelease"></a></p>
<h3 id="creating_a_snapshot_release">Creating a snapshot release</h3>
-<p>TBD. This isn't a necessary step in the release process but should still be
-documented here.</p>
+<p>This is important to do when releasing from trunk as other bundles may want
+to continue to depend on the -SNAPSHOT version while the release is voted through.</p>
<h3 id="jira_preparation">JIRA preparation</h3>
<ul>
<li>After initial release discussion on the mailing list you should have a list of JIRA issues that are required in the release. If not, the default assumption is 'everything that has been fixed since the last release'.</li>
Modified: websites/production/aries/content/development/versionpolicy.html
==============================================================================
--- websites/production/aries/content/development/versionpolicy.html (original)
+++ websites/production/aries/content/development/versionpolicy.html Wed Mar 16 10:13:33 2011
@@ -239,25 +239,6 @@
<p>The Aries project aims to implement OSGi semantic versioning as described <a href="www.osgi.org/wiki/uploads/Links/SemanticVersioning.pdf">here</a>.</p>
<p>The implementation of semantic versioning has a number of practical implications for managing a project. These are
outlined in this section. </p>
-<h2 id="bundle_versions">Bundle versions</h2>
-<p>OSGi semantic versioning applies to bundles as well as packages. When releasing a new version of a bundle
-the change in the bundle version should give some indication of nature of the changes to the bundle.
-In Aries the bundle version is the same as version of the Maven artifact version.
-During development, in trunk, the Maven artifact version may be:</p>
-<ul>
-<li>either x.y.z Where x.y.z is the most recent release of the bundle</li>
-<li>or x.y.(z+1)-SNAPSHOT Indicating that the bundle has changed since it was last released.</li>
-</ul>
-<p>Immediately after a release the Maven version is set the same as the release. Bundles which depend
-on the bundle will pick up the released version. When a developer first makes a change to the bundle the version
-is changed to be a SNAPSHOT version, indicating to a release manager that the bundle is a candidate for release.</p>
-<p><strong>EITHER</strong>
-At release time the release version of the bundle must be assigned by the release manager after reviewing
-the changes to the bundle's package versions since the last release.</p>
-<p><strong>OR</strong>
-Whenever a developer makes a change to a package version they must check the bundle version and, if necessary, modify the bundle
-version in line with changes that have been made to packages. In this case the RM has no
-additional work - correct bundle semantic versioning is the responsibility of the developer making the code changes</p>
<h2 id="package_versions">Package versions</h2>
<h3 id="exported_packages">Exported packages</h3>
<p>Versions are usually specified in packageinfo files with the source code. The default-parent pom is
@@ -265,8 +246,8 @@ configures (in the build resources secti
resources section it replaces what is inherited from the default-parent, so you may need to reproduce
the section which specifies where packageinfo can be found.</p>
<p>Developers <strong>must</strong> increment the versions in packageinfo files in strict accordance with OSGi
-semantic versioning when they make changes to a package. The version should relate to the most
-recent release of the package and not to the version found in trunk. For example:</p>
+semantic versioning when they make changes to a package. The version should relate to the <strong>most
+recent release of the package</strong> and not to the version found in trunk. For example:</p>
<h4 id="scenario_1_making_changes_to_a_package_with_released_version_abc">Scenario 1, making changes to a package with released version a.b.c</h4>
<ul>
<li>Developer A fixes a bug in the package and increments it's version to a.b.c+1</li>
@@ -280,13 +261,39 @@ recent release of the package and not to
<h4 id="scenario_3_making_changes_to_a_package_with_released_version_abc">Scenario 3, making changes to a package with released version a.b.c</h4>
<ul>
<li>Developer A fixes a bug in the package, and increments its version to a.b.c+1</li>
-<li>Developer B deletes a method from an interface and increases the package version to a+1.0.0</li>
+<li>Developer B deletes a method from an interface and increases the package version to a+1.0.0. Note the final '0' here, developer B's change is more significant
+so there is no need to reflect Developer A's change with a micro version of '1'. Indeed, a version of a+1.0.1 would imply a bug fix to version a+1.0.0.</li>
</ul>
<h3 id="importing_packages">Importing packages</h3>
-<p>The bnd default version range policy for imports is the consumer policy (==, +), you may need to
-override this if you want to be more prescriptive about specific Aries imports.
+<p>The bnd default version range policy for imports is the consumer policy (==, +). Implementers of interfaces will need to
+override this. For example as an implementer of an interface the version range
+would be the provider policy (==,=+).
The policy can be set by using the Maven property <aries.osgi.version.policy>, see the default-parent
-pom for an example.</p></div>
+pom for an example.</p>
+<h2 id="bundle_versions">Bundle versions</h2>
+<p>OSGi semantic versioning applies to bundles as well as packages. When releasing a new version of a bundle
+the change in the bundle version should give some indication of nature of the changes to the bundle.
+In Aries the bundle version is the same as version of the Maven artifact version.
+During development, in trunk, the Maven artifact version may be:</p>
+<ul>
+<li>either x.y.z Where x.y.z is the most recent release of the bundle</li>
+<li>or x.y.(z+1)-SNAPSHOT Indicating that the bundle has changed since it was last released.</li>
+</ul>
+<p>Immediately after a release the Maven version is set the same as the release. Bundles which depend
+on the bundle will pick up the released version. When a developer first makes a change to the bundle the version
+is changed to be a SNAPSHOT version and some change made to the bundle version number,
+indicating to a release manager that the bundle is a candidate for release.</p>
+<p>There are two possibilities for assigning a bundle version number at release time:</p>
+
+<p><strong>EITHER</strong>
+At release time the release version of the bundle must be assigned by the release manager after reviewing
+the changes to the bundle's package versions since the last release. This is not a particularly time consuming task as long as
+packageinfo files are used for versioning packages.</p>
+<p><strong>OR</strong>
+Whenever a developer makes a change to a package version they must check the bundle version and, if necessary, modify the bundle
+version in line with changes that have been made to packages. In this case the RM has no
+additional work (although it might be argues that an RM should check the bundle version - this is then pretty much the same amount of work as actually assigning it)
+- correct bundle semantic versioning is the primary responsibility of the developer making the code changes.</p></div>
<!-- Content -->
</td>
</tr>