Mailing-List: contact dev-help@accumulo.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@accumulo.apache.org
MIME-Version: 1.0
In-Reply-To: <51A3FCAF.80909@gmail.com>
References: <51A3FCAF.80909@gmail.com>
Date: Mon, 27 May 2013 21:37:37 -0400
Message-ID: 
 <CAL5zq9bH8y0FyjXmmfXhWPj8axosn9dZ7+u-R1DK4Y-WM1YoWg@mail.gmail.com>
Subject: Re: SCM Section of 1.5.0 pom
From: Christopher <ctubbsii@apache.org>
To: Accumulo Dev List <dev@accumulo.apache.org>
Content-Type: text/plain; charset=ISO-8859-1

On Mon, May 27, 2013 at 8:39 PM, Josh Elser <josh.elser@gmail.com> wrote:
> Poking around at the changes that Christopher made in regards to making
> releases, I noticed in the 1.5.0 tag from subversion, the 'scm' section
> still has connection, developerConnection and url pointing to RC5. [1]
>
> I assume this was just an oversight. Is this something that we should just
> be changing on that tag since the vote passed?

Hrmm. We definitely should not edit the tag after the vote passes. It
should remain exactly as it was when it was voted on, as it affects
signatures, and everything.

So, this gets updated by the maven-release-plugin automatically. I
don't think it's that important. It does get used by the
maven-site-plugin. This field is used to generate a page on the
maven-site that tells users how to access the source code. If we ever
start generating the maven-site, we're going to want that to be
correct. However, we don't want to make the release process harder by
going back to manual ways of doing things that are automated by
maven-release-plugin.

I suppose there are two options to deal with this specific "gotcha"
(svn-specific... git may be different... somebody else will have to
advise for that):

1) never delete an RC tag, so it can still be referenced with the RC#
suffix, even though it's identical to a second "tag" (eg. use "svn cp"
instead of "svn mv" after a release vote passes).

2) tell the release-plugin to create the tag in its final location,
then "svn mv" it to the RC name manually, then "svn mv" it back if it
passes.

Maybe we should request a feature for the maven-release-plugin to
support release candidates better?

> A bit of a follow-on, mostly for Christopher. If you get hit by a bus, any
> instructions for the rest of us on any other "gotchas" that you came across?
> Is this worthy of a page (public or just developer-based) devoted to the DOs
> and DONTs in making a release?
>
> [1] http://svn.apache.org/repos/asf/accumulo/tags/1.5.0/pom.xml

The build is pretty much completely automated and self-documented (it
activates the correct profiles automatically). To actually do a
release, the steps are pretty much, "execute `mvn release:prepare
release:perform`". For convenience, I added this command to
assemble/build.sh, but really, as long as you have all the
prerequisites to build all the desired artifacts, the build is pretty
much automated from start to finish.

I suppose I could add some notes:

DO use gpg-agent.
DO set a default key in ~/.gnupg/gpg.conf if you have more than one secret key.
DO set a gpg-agent cache timeout long enough to execute the build, and
cache your passphrase in gpg-agent before you build.
DO use a system with all the prerequisites to build native libraries,
RPMs, and DEBs, as well as thrift (including ruby, c++, python, and
java support).
DO make sure the correct version of all the java binaries are on the
path, and none from other versions that may be installed (like
javadoc... which produces very different documentation, depending on
the version).
DO cache your SVN credentials (I recommend using subversion-gnome to
put your passphrase in gnome-keyring rather than let subversion store
it in plain text).
DO build in an account where your username is the same as your Apache ID.
DO update the CHANGES file prior to building, in a separate commit.
DO close the staging repository so no further artifacts can be
deployed to it, and so others can view it for voting.
DO edit the recommended tag, when prompted by the
maven-release-plugin, to include the specific tag number (the default
when it prompts is simply $version-RC, but you want $version-RC#).

DON'T make things difficult by adding a bunch of manual steps to the
build process
DON'T build on a dirty workspace (use a clean checkout)
DON'T try to do a release from an IDE (use the command line)
DON'T try to install all the LaTeX packages manually (use `yum install
texlive*` or equivalent)
DON'T build remotely, unless you're using screen (if the SSH
connection dies, you won't know what state your workspace is in, or
whether it has already made commits to SVN without checking)
DON'T accidentally release the wrong staging repository.

There's some additional SVN gotchas to worry about:

1) The maven-release-plugin creates 3 commits, if it is successful:
one to change the version number to the release version, one to copy
the branch with the release version to the tag, and one to change the
version number in the branch to the next SNAPSHOT version. These
changes will interfere with merges from branch to trunk. It would be
best to merge these 3, as well as the commit to edit CHANGES, all to
trunk as a --record-only merge, so that future range merges (as in
`svn merge -r 1:HEAD branches/1.5/ trunk/`) go smoothly. To do this,
identify the specific commits, C1,C2,C3,C4, and merge them like: `svn
merge -r C1,C2,C3,C4 --record-only branches/1.5/ trunk/`, and then
commit the changes in trunk/.

2) To roll back a failed RC in SVN, do a reverse merge of the 3
maven-release-plugin commits, as well as the commit to edit the
CHANGES file, onto itself in reverse order, with a '-' sign prefixed
to each, as in: `svn merge -c -C4,-C3,-C2,-C1 .`; you'll want to do
this on a checkout of the whole svn repository, and not just your
branch, because one of those commits represents an RC tag, which is
outside of your branch, and it's easier to delete it in the same step,
than figure out which of the three commits represents the tag, ignore
it during the reverse merge, and separately delete the RC tag. After
you do the reverse merge, commit it. This single commit (I'll call C5)
represents squashing C1-C4, and reversing them all, but it will affect
future merges from the branch to trunk, so you'll want to do a
--record-only merge of C5 onto trunk from the branch, to ensure clean
range merges from now on (see previous paragraph).


--
Christopher L Tubbs II
http://gravatar.com/ctubbsii