You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by br...@apache.org on 2015/03/01 18:59:25 UTC
svn commit: r1663139 - in /commons/cms-site/trunk/content/xdoc/releases:
prepare.xml release.xml
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>
<properties>
<commons.componentid>foo</commons.componentid>
@@ -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: <your apache ID></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'>