commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From brit...@apache.org
Subject svn commit: r1663139 - in /commons/cms-site/trunk/content/xdoc/releases: prepare.xml release.xml
Date Sun, 01 Mar 2015 17:59:25 GMT
Author: britter
Date: Sun Mar  1 17:59:25 2015
New Revision: 1663139

URL: http://svn.apache.org/r1663139
Log:
Document how to publish releases using git

Modified:
    commons/cms-site/trunk/content/xdoc/releases/prepare.xml
    commons/cms-site/trunk/content/xdoc/releases/release.xml

Modified: commons/cms-site/trunk/content/xdoc/releases/prepare.xml
URL: http://svn.apache.org/viewvc/commons/cms-site/trunk/content/xdoc/releases/prepare.xml?rev=1663139&r1=1663138&r2=1663139&view=diff
==============================================================================
--- commons/cms-site/trunk/content/xdoc/releases/prepare.xml (original)
+++ commons/cms-site/trunk/content/xdoc/releases/prepare.xml Sun Mar  1 17:59:25 2015
@@ -17,7 +17,7 @@
 -->
 
 <document>
- 
+
  <properties>
   <title>Preparations for a Release</title>
   <author email="dev@commons.apache.org">Apache Commons Documentation Team</author>
@@ -64,7 +64,7 @@
       <p>
       A commons committer (normally one of the development team) should post an email to
the
       development list proposing that a release be made and nominating a release manager.
-      Typically, the proposer volunteers as the release manager and it passes by 
+      Typically, the proposer volunteers as the release manager and it passes by
       <a href='http://www.apache.org/foundation/glossary.html#LazyConsensus'>lazy consensus</a>.
       </p>
     </subsection>
@@ -95,17 +95,18 @@
       </p>
     </subsection>
 
-    <subsection name='Consider a Release Branch'>
+    <subsection name='Using a Release Branch'>
       <p>
-      Consider whether a release branch is needed before preparing for the new release. In
general, 
-      Commons components are small enough that there is no need for a release branch, but
if 
-      active development will continue on the next version while a release is being made
then 
-      trunk should be branched to allow this.
-      If a release branch is taken then work will be required to merge any changes back 
+      Consider whether a release branch is needed before preparing for the new release. In
general,
+      Commons components are small enough that there is no need for a release branch, but
if
+      active development will continue on the next version while a release is being made
then
+      trunk should be branched to allow this.<br />
+      All components using git should always use a release branch.<br />
+      If a release branch is taken then work will be required to merge any changes back
       into the trunk.
       </p>
       <p>
-      The following is one way to create a release branch:
+      <strong>Creating a release branch with SVN</strong>
       </p>
       <pre>
         cd to the project's base directory in your subversion working copy.
@@ -119,7 +120,7 @@
       since the last svn update this can cause "svn log -v" on the new directory to report
files as
       having been (R)eplaced.
       </p>
-      <p>Alternatively, use "svn cp URLsrc URLtag"</p> 
+      <p>Alternatively, use "svn cp URLsrc URLtag"</p>
       <pre>
         svn cp -m "Creating foo-1.2-release branch" \
             https://svn.apache.org/repos/asf/commons/proper/foo/trunk \
@@ -130,16 +131,23 @@
       a clean copy is made.
       </p>
       <p>
-      The description below assumes a release is being prepared using the code in trunk.
The process is nearly
-      identical when preparing from a release branch: only the directory in which the work
is performed is different.
+      <strong>Creating a release branch with git</strong>
+      </p>
+      <pre>
+        git checkout -b release
+      </pre>
+      <p>
+      The description below assumes a release is being prepared using the code in trunk for
SVN based components.
+      The process is nearly identical when preparing from a release branch: only the directory
in which the work is
+      performed is different. All git specific commands assume that you're on the release
branch.
       </p>
     </subsection>
     <subsection name='Check Compatibility'>
       <p>
     Consult the <a href='versioning.html'>Commons Versioning Guidelines</a> and
check
     that the current level of compatibility is suitable for the proposed version number.
-    Check the current level of compatibility in the code. Tools like 
-    <a href='http://clirr.sourceforge.net'>Clirr</a> and 
+    Check the current level of compatibility in the code. Tools like
+    <a href='http://clirr.sourceforge.net'>Clirr</a> and
     <a href='http://www.jdiff.org'>JDiff</a> are very useful. Both support Ant
and Maven.
       </p>
     </subsection>
@@ -172,7 +180,7 @@
     </pre>
         </p>
         <p>
-    If the component uses checkstyle, findbugs or PMD tools, examine the reports and fix
all 
+    If the component uses checkstyle, findbugs or PMD tools, examine the reports and fix
all
     problems.
         </p>
     </subsection>
@@ -184,13 +192,13 @@
       the maven-assembly-plugin configuration in the pom.  Make sure that all (and only)
files
       that should be included in the source and binary distributions are included in the
fileset
       elements of the descriptors.  Look at some recently released components' descriptors
for comparison.
-      At a minimum, both source and binary distributions <strong>must</strong>
include the release notes, license and 
+      At a minimum, both source and binary distributions <strong>must</strong>
include the release notes, license and
       notice files.
       </p>
       <p>
       Update the version numbers in pom.xml and build.xml to the new release version, in
this example, 1.2.
       For Maven builds, make sure that the build properties are properly set. Review the
<code>properties</code>
-      section of the pom: 
+      section of the pom:
       <pre>
       &lt;properties&gt;
         &lt;commons.componentid&gt;foo&lt;/commons.componentid&gt;
@@ -223,8 +231,13 @@
       are set correctly. Generate and check in a new download page for the component:
       <pre>
       mvn [-N] commons:download-page [-Dcommons.release.version=m.n]
-      svn commit -m "Updated download page in preparation for 1.2 release." src/site/xdoc/download_foo.xml
</pre>
-      
+      svn commit -m "Updated download page in preparation for 1.2 release." src/site/xdoc/download_foo.xml
+      </pre>
+      Or when using git:
+      <pre>
+      git commit -am "Updated download page in preparation for 1.2 release." src/site/xdoc/download_foo.xml
+      </pre>
+
       Note that the target directory must exist beforehand, and that for a multi-module project
the <code>-N</code>
         (non-recursive) parameter should be specified on the <code>mvn</code>
command line.
       The release version can be overridden with -Dcommons.release.version=m.n if you want
to create the new file
@@ -235,8 +248,8 @@
       files are specified in the target or sub-targets and should be verified similarly to
above.
       </p>
       <p>
-      Test the "Ant dist" or "mvn assembly:assembly" command and inspect the tars/zips and
jars produced. 
-      Verify that 
+      Test the "Ant dist" or "mvn assembly:assembly" command and inspect the tars/zips and
jars produced.
+      Verify that
       <ol>
       <li> "Ant dist" or "mvn site" succeeds from the unpacked source distribution.</li>
       <li> The jar manifests include LICENSE and NOTICE files and the contents of these
files are correct.</li>
@@ -253,7 +266,7 @@
   Implementation-Vendor-Id: org.apache
   Implementation-Title: org.apache.commons.foo
   Implementation-Vendor: The Apache Software Foundation
-  Implementation-Version: 1.2 
+  Implementation-Version: 1.2
   Built-By: &lt;your apache ID&gt;</pre></li>
       <li> "mvn site" generates the documentation correctly and all links are working.</li>
       </ol>
@@ -306,6 +319,7 @@
           cd ..
           svn log -v -rNNNN:HEAD trunk > commits-since-last-release.txt
         </pre>
+        <em>TODO:</em> Equivalent for git
       </p>
       <p>
         This will result in a file that contains info on each commit that affected at
@@ -382,7 +396,7 @@
     read easily without word wrap.
     </p>
   </subsection>
-    <subsection name='Test Against Listed Dependencies'>    
+    <subsection name='Test Against Listed Dependencies'>
     <p>
     If you are using Maven to execute the unit tests associated with the component then
     there is nothing to do here; Maven will automatically perform the tests using the
@@ -408,10 +422,10 @@
         Check that the jar contains a copy of the license in the META-INF directory.
         </p>
         <p>
-        Check that the years in the copyright statement in the NOTICE file are correct. 
+        Check that the years in the copyright statement in the NOTICE file are correct.
         </p>
         <p>
-        Developer documentation on how to apply the Apache License 
+        Developer documentation on how to apply the Apache License
         can be found in <a href="http://www.apache.org/dev/apply-license.html">Applying
the Apache License, Version 2.0</a>
         and <a href="http://www.apache.org/legal/src-headers.html">ASF Source Header
and Copyright Notice Policy</a>
         </p>
@@ -435,7 +449,7 @@
         </p>
         <p>
         No. The new license allows for a NOTICE file that contains such attribution
-        notices (including the Apache attribution notice).  See 
+        notices (including the Apache attribution notice).  See
         </p>
         <p>
         <code><a href="http://www.apache.org/licenses/example-NOTICE.txt">http://www.apache.org/licenses/example-NOTICE.txt</a></code>
@@ -445,7 +459,7 @@
         httpd-2.0 distribution.
         </p>
     </subsection>
-    
+
     <subsection name='Update the download xml file'>
         <p>
         The download page on the website is created from the file <code>src/site/xdoc/download_{component}.xml</code>.
@@ -454,7 +468,7 @@
         Check that the changes (if any) are correct and commit the updated file.
         </p>
     </subsection>
-    
+
     <subsection name='Check NOTICE.txt'>
         <p>
         The component should contain a NOTICE.txt (next to the LICENSE.txt).
@@ -477,12 +491,12 @@
     </subsection>
     <subsection name='Tag the Release Candidate'>
         <p>
-        Once all the preparations agreed in the release plan has been completed, create a
Release Candidate. 
+        Once all the preparations agreed in the release plan has been completed, create a
Release Candidate.
         Before creating the tag from which the release candidate will be generated, run the
distribution build
         and double check that everything is still fine.
         </p>
         <p>
-        Make sure that the build version number corresponds to the release version.  For
example, 
+        Make sure that the build version number corresponds to the release version.  For
example,
         <code>commons-foo-1.2</code>.  What you are preparing at this point is
a candidate for release,
         which we will vote on and then push directly to the mirrors.  Clean build, run the
unit tests
         and check that the javadocs  have the correct version number.  Check in all changes.
@@ -491,7 +505,7 @@
           Now create the tag for the release candidate.  There are two options how to do
that,
           you can either use the Maven release plugin or create the tag manually.  In either
case, record
           the svn revision number, you'll need it for the release vote mail.</p>
-      
+
       <h4>Manual Method<a name="Manual_Method"></a></h4>
         <p>Create a clean SVN workspace for the release candidate:</p>
       <pre>
@@ -504,12 +518,12 @@
       mvn versions:set -DnewVersion=1.2 -DgenerateBackupPoms=false
       </pre>
 
-        
+
         <p>Edit the SCM entries in the POM. Note: use the final tag, without any RC
suffix.
         Do <code>svn diff</code> and <code>svn status</code> to check
that the changes are OK.
         These should only show changes to the POMs.</p>
 
-        <p>Create the RC tag, by copying the tag workspace to SVN as below. 
+        <p>Create the RC tag, by copying the tag workspace to SVN as below.
           The tag name should include the component name, as this makes it easier to distinguish
checkouts.
           Try to follow the existing naming convention so the tag names will sort in a reasonable
order.
           For example NET uses NET_M_N_RC1, and LANG has a similar convention.
@@ -526,6 +540,25 @@
         It's important to only have SNAPSHOT versions in trunk; only tags should have non-SNAPSHOT
versions.
         Also, by leaving trunk unchanged, nothing needs to be reverted if the RC vote fails
and the Rc needs to be re-rolled.
       </p>
+
+      <strong>Tagging with git</strong>
+
+      <p>
+      After editing the version fields in the POMs:
+      </p>
+      <pre>
+      git commit -am "Update version numbers for commons foo release 1.2"
+      git tag -s 1.2-RC1 -m "Tag commons foo release 1.2 RC1"
+      git push
+      </pre>
+
+      <p>
+      If this is the first release using git and there has never been a release branch, git
will ask you to set the upstream branch:
+      </p>
+      <pre>
+      git push -u origin/release
+      </pre>
+
       <h4>Maven Release Plugin<a name="Maven_Release_Plugin"></a></h4>
         <p>When using the release plugin, please verify that your poms will not lose
content when they are rewritten during the
           release process.</p>
@@ -543,26 +576,28 @@
 
         <p>Remember to do <code>mvn release:clean</code> before you start
the real release process.
           If everything is ok, run:</p>
-      <pre>  
+      <pre>
       mvn release:prepare
       </pre>
 
       <p>
-        The Maven release:prepare goal updates the trunk tag to the next SNAPSHOT release.

+        The Maven release:prepare goal updates the trunk tag to the next SNAPSHOT release.
         If the RC vote fails, this will need to be reverted before re-rolling the RC.
         (the manual method described above avoids this problem)
       </p>
-      
+
+      <em>TODO:</em> Does the Maven Release plugin work with git?
+
     </subsection>
     <subsection name="Create the Release Candidate">
-        
-        <p>
+
+    <p>
     Build distributions from a fresh checkout of the RC tag.
     Build the code with the target version of Java if possible.<br />
     If the version of Maven you are using requires a more recent version of Java than the
code you are
     building, then use the appropriate <code>java-1.x</code> profile to ensure
that compilation and testing is done
     with the correct Java version. This will catch any accidental use of methods etc. that
are not in
-    the target Java version libraries. 
+    the target Java version libraries.
     See <a href="../commons-parent-pom.html#Testing_with_different_Java_versions">Testing
with different Java versions</a>
     for further details.
     (the compiler.source and compiler.target versions only affect source syntax and class
file format)
@@ -587,12 +622,12 @@
         It works if you specify the passphrase when invoking mvn (<code>-Dgpg.passphrase=***</code>)
         -- this is not recommended as it may expose the plain password in process lists or
shell history files --
         or run <code>gpg-agent</code> before starting mvn.</p>
-      <p>Version 1.6 of the GPG plugin supports storage of the password using 
+      <p>Version 1.6 of the GPG plugin supports storage of the password using
       <a href="http://maven.apache.org/plugins/maven-gpg-plugin/sign-mojo.html#passphraseServerId">Maven
password encryption</a>
       This uses the server id of <code>gpg.passphrase</code> by default.
       However Maven encryption is not inherently safe unless the master password is secured
in some way.
       For example by storing the security.xml file in a password-protected OS file or on
removable storage.
-      Note that recovering from a compromised GPG key is not easy, so the password needs
to be very carefully guarded. 
+      Note that recovering from a compromised GPG key is not easy, so the password needs
to be very carefully guarded.
       </p>
       <p>Unfortunately this uploads more than should be part of the Maven repository,
in particular the binary and source
         distribution <code>.tar.gz</code> and <code>.zip</code> files
are there as well.  Before you
@@ -613,7 +648,7 @@
         svn mkdir -m "Creating initial directory structure for foo" https://dist.apache.org/repos/dist/dev/commons/foo/binaries
         svn mkdir -m "Creating initial directory structure for foo" https://dist.apache.org/repos/dist/dev/commons/foo/source
       </pre>
-      <p>Then check out <code>https://dist.apache.org/repos/dist/dev/commons/foo</code>
and copy the tarballs, checksums and 
+      <p>Then check out <code>https://dist.apache.org/repos/dist/dev/commons/foo</code>
and copy the tarballs, checksums and
         PGP signatures to the appropriate directories.  You can find those artifacts inside
your local Maven repository.
         The procedure will be something like (where <code>release_path</code>
points to your working copy of the dist repository):</p>
       <pre>
@@ -691,7 +726,7 @@
 
   KEYS:
   https://www.apache.org/dist/commons/KEYS
-          
+
   Please review the release candidate and vote.
   This vote will close no sooner that 72 hours from now, i.e. after 0400 GMT 31-March 2010
 
@@ -705,12 +740,12 @@
   Lucky RM </pre>
         </p>
         <p>
-        Votes from members of the Commons PMC are binding, however votes from other committers,
users and 
+        Votes from members of the Commons PMC are binding, however votes from other committers,
users and
         contributors are welcomed.
         If the <code>[VOTE]</code> is successful then continue. Release VOTEs
should be left open for a
         minimum of 72 hours so community members have ample opportunity to download, review
and test the
         release candidate.  It is a good practice to, as above, specify the closing time
of the VOTE in
-        the VOTE message. 
+        the VOTE message.
         </p>
     <p>
     If the vote fails, then fix the problem and create a new release candidate (including
creating another tag;
@@ -721,7 +756,7 @@
     accompanied by patches and/or commits to fix problems.  Always start a new VOTE thread
to vote on a new RC.
     </p>
         <p>
-        Once a vote is successful, post a <code>[RESULT] Release Foo 1.2</code>
email to 
+        Once a vote is successful, post a <code>[RESULT] Release Foo 1.2</code>
email to
         <strong>dev@commons.apache.org</strong> as a reply to the original posting.
         This email should contain a summary of the voters/votes that were cast, eg
         <pre>
@@ -735,7 +770,7 @@
         Note that binding the VOTEs recorded need to be clearly designated in the RESULT.
         This may be done by either stating only the binding votes (and indicating that to
be the case)
         or by adding <code>(non-binding)</code> to those which are not.
-        It is best practice to indicate how each person voted. 
+        It is best practice to indicate how each person voted.
         This allows any mistakes to be caught and corrected early.
         If you do vote, please check the results to ensure that your vote has been correctly
tallied.
         </p>
@@ -749,7 +784,7 @@
 
   <section name='Things To Look For When Inspecting A Release Candidate'>
     <p>
-    There are a number of common things that releases fail on. 
+    There are a number of common things that releases fail on.
     </p>
 
     <subsection name="API Changes">
@@ -788,7 +823,7 @@
     <p><strong>Maven Build</strong></p>
     <p>
     The Maven build has been modified to include two <strong><i>non standard</i></strong>
attributes
-    in the jar's manifest to indicate the <code>maven.compile.source</code> and

+    in the jar's manifest to indicate the <code>maven.compile.source</code> and
     <code>maven.compile.target</code> properties used to create the jar. This
serves two purposes:
       <ul>
          <li>To provide comfort to users regarding JVM compatibility.</li>
@@ -840,7 +875,7 @@
 
    <section name='Feedback'>
         <p>
-        Feedback - yes please! 
+        Feedback - yes please!
         </p>
         <p>
         Comments, critiques and error reports -

Modified: commons/cms-site/trunk/content/xdoc/releases/release.xml
URL: http://svn.apache.org/viewvc/commons/cms-site/trunk/content/xdoc/releases/release.xml?rev=1663139&r1=1663138&r2=1663139&view=diff
==============================================================================
--- commons/cms-site/trunk/content/xdoc/releases/release.xml (original)
+++ commons/cms-site/trunk/content/xdoc/releases/release.xml Sun Mar  1 17:59:25 2015
@@ -126,8 +126,33 @@
     </p>
   </subsection>
 
-  <subsection name="4 Create Subversion Tag for the Final Release">
-    <p>Copy the release candidate tag in subversion to a name without RC in its name.</p>
+  <subsection name="4 Create SCM Tag for the Final Release">
+    <p>Copy the release candidate tag in subversion to a name without RC in its name:</p>
+    <pre>
+    svn cp -m "Release commons foo 1.2 based on RC 1" \
+      https://svn.apache.org/repos/asf/commons/proper/foo/tags/foo-1.2-RC1 \
+      https://svn.apache.org/repos/asf/commons/proper/foo/tags/foo-1.2
+    </pre>
+
+    <strong>Final tag when using git</strong>
+    <p>Make sure you have the latest changes on the master branch and the release branch:</p>
+    <pre>
+    git checkout release
+    git pull origin master
+    git pull origin release
+    </pre>
+    <p>Now create the final tag, bump the version number to the next development version,
+      commit the new version and merge the release branch back into the master branch, so
+      that the master branch also has the new development version:
+    </p>
+    <pre>
+    git tag -s foo-1.2 -m "Create Commons foo 1.2 release tag"
+    mvn versions:set -DnewVersion=1.3-SNAPSHOT -DgenerateBackupPoms=false
+    git commit -am "Bump to next development version"
+    git checkout master
+    git merge release
+    git push
+    </pre>
   </subsection>
 
   <subsection name='5 Test Main Site Downloads'>



Mime
View raw message