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="[email protected]">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>[email protected]</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'>
