Date: 2005-02-07T16:08:43
Editor: HowardLewisShip
Wiki: Jakarta Tapestry Wiki
Page: ReleaseChecklist
URL: http://wiki.apache.org/jakarta-tapestry/ReleaseChecklist
no comment
New Page:
#pragma section-numbers off
There are several steps between a consensus forming about a new release, and
actually delivering the release. This has been an area of
confusion, and the Tapestry team has certainly trodded on a few Jakarta PMC
toes. Let's try and get this right in the future!
* Note: certain aspects of this discussion apply to 3.1 and above (such as
running the build and packaging the results).
= Discuss =
This isn't necessarily a step, but should be considered. Before initiating a
vote, generate a discussion. Send mail to the developer mailing list with the
subject {{{[DISCUSS] Release 3.1-beta-2}}} (adjust for the actual release being
proposed).
Generally speaking, we shouldn't go forward to a vote unless we're pretty sure
of the outcome ahead of time.
= Vote Mail =
Again, email to the developer mailing list, as {{{[VOTE] Release 3.1-beta-2}}}.
Try to be specific in the email about the timetable, who would do the vote, how
long it will last, the rationale, etc. Don't forget to include your +1 vote.
For example:
{{{
To: tapestry-dev@xxxxxxxxxxxxxxxxxx
Subject: [VOTE] Release 3.1-beta-2
The latest bug fixes really seem to be kicking things into high gear. We should
get a release out the door to spot
more problems and see if people can follow the new documentation. This vote
will run for a week, a +1 is to release Tapestry 3.1-beta-2.
I'll be able to generate the release over the weekend following the vote.
Howard M. Lewis Ship: +1 (binding)
}}}
Also remember the meritocracy rules ... a -1 indicates a veto, but only counts
if you can provide a reasonable rationale.
* To be honest, I'm confused about whether release votes can be vetoed, or
whether it is simple majority rules. Clarification, anyone?
Again, ''wait'' for all the votes to come in, or for the clock to finish. We
have a couple of relatively inactive members (which is a total shame), but we
have
to follow the rules.
The commiter who initiates the vote has ''volunteered to be the release
engineer''. You wanted it enough to start a vote, be prepared to carry it
through. You will be responsible for
all the remaining steps. If you need help, ask!
= Voting =
Committers can make it easy on the release engineer by adding "(binding)" to
their vote. Non-committers should not do this .. their votes are important, but not
binding.
= Result Mail =
Following the last vote mail, send a {{{[RESULT]}}} mail to the development
list '''and''' CC {{{pmc@xxxxxxxxxxxxxxxxxx}}}. We have enough Jakarta PMC
members on the Tapestry team that
we don't require authorization from the Jakarta PMC, but we '''do''' have to
notify them.
The mail should include the text of the vote and ''all'' responses; binding
votes first, non-binding votes second.
Following the [RESULT] mail, everyone (except the release engineer) should hold
back on check ins until the all clear is given.
= Final Changes =
You should update {{{status.xml}}}:
* Record the vote in a <vote> stanza
* Update the {{{version}}} and {{{date}}} attributes of the property
<release> stanza
In some cases, the version may need to be updated; it may change from, say,
"3.1-alpha-3-snapshot" to "3.1-beta-1" if we decide to follow 3.1-alpha-2 with
3.1-beta-1.
Make sure to update {{{version.properties}}} as well.
Finally, take a peek at the {{{KEYS}}} file. You'll sign the KEYS file using
your GnuPG or PGP key. Instructions are inside the file itself.
This KEYS file is how diligent users validate that the final release is, in
fact, authenticated and valid.
'''Check in''' these changes.
= Run the build =
I prefer to run the build then label ... occassionally you find a minor issue
that is wrong and needs to be a last minute fix.
{{{ant -emacs dist}}}
This will perform a final, clean build of the Tapestry framework, contrib,
examples and documentation. It will then package the results,
ready for upload.
This takes about 15 minutes on my laptop. The framework unit tests can take
up-to three minutes by themselves (those damn integration tests, TestMocks,
take forever). And the test suites are run twice: once for the build, once to
collect code coverage information. Forrest is also time consuming.
The final files will be placed in {{{target/dist}}}. There are three files
generated:
* tapestry-''version''.tar.gz -- main distribution; compiled binaries plus
source
* tapestry-''version''.zip -- larger, zip version of above
* tapestry-''version''-docs.tar.gz -- documentation as a web site
In addition, MD5 hash files are created for each of the three files (these are
the .md5 files in target/dist).
It doesn't hurt to give these files a once over to make sure they built
correctly (occasionally, build file errors cause erronous files to be included
in the distribution).
The build scripts should end with a reminder to sign the release.
= Label The Release in CVS =
If the release files are all set, then it's time to lock down the versions in
CVS.
Use CVS to label HEAD as {{{release-3-1-beta-2}}} (adjust for the correct
release). CVS labels can't include periods, so translate those to dashes.
= Sign the release =
Change to the target/dist directory and sign the files. Here's a quicky for
doing it using GnuPG and Bash:
{{{
for i in *.gz *.zip
do
echo "Signing " $i
gpg -a -b --force-v3-sigs $i
done
}}}
Lucky you ... you get to type your GnuPG pass phrase three times in a row.
Hey, it used to be five!
The signatures show up as .asc files.
= Upload the release =
Ant handles this for you:
{{{ant -emacs install-dist install-docs install-maven
-Ddist.install.user='''userid'''}}}
You need to provide your Jakarta login user id (you can also update
{{{project.properties}}} for this).
You will be prompted for your password ... in cleartext yet. Sorry! Have to
do it. Ant's ssh support doesn't seem to know from ssh-agent.
The {{{install-dist}}} target installs the main distribution files (plus md5
sums and PGP signatures, and KEYS) into
/www/www.apache.org/dist/jakarta/tapestry. This directory is mirrored to all
the Apache download mirrors.
The {{{install-docs}}} target uploads the documentation and expands it to form
the Tapestry home page.
The {{{install-maven}}} target copies the Tapestry JAR files to
/www/www.apache.org/dist/java-repository/tapestry/jars, where
they will be mirrored to ibiblio.net, so the whole world can access them using
Maven.
You should only have to enter your pass phrase once.
= Send The All Clear =
Send mail to the developer mailing list ... the the checkins begin!
'''Note:''' The first checking should increment the {{{project.version}}} release
number, and add "-snapshot" ... i.e., {{{3.1-beta-4-snapshot}}}.
Also, don't forget to create a '''new''' <release> stanza!
''Perhaps the release engineer should do this before sending the all clear?''
= Test the Downloads =
Make sure all the files you just uploaded are readable! Log into
jakarta.apache.org and fix permissions if they are not!
= Wait 24 hours =
It takes up-to 24 hours for the mirros to synchronize. If you send out the
mail too soon, people who go to download the lastest and greatest will be
dissapointed.
= Update jakarta-site2 =
This is a whole process onto itself; you need Subversion to get the
jakarta-site2 stuff. It's yet-another XML-like limited HTML syntax (related to
Forrest markup, but not quite). Once you check it out, there are directions on
how to proceeed.
Anyway, when I last checked, you would use the build scripts to rebuild the
documentation, then check in the ''derived HTML files'' as well as the XML
source files. Yes, I cringe.
You need to do three things:
* Update the correct files in news. It will likely be
{{{xdocs/site/news/news-2005-q3.xml}}} or somesuch.
* Update {{{xdocs/index.xml}}} and add an entry pointing to your new news item.
* Update {{{xdocs/site/binindex.xml}}}.
Each news file covers one quarter of one year; there will be many examples
(Tapestry and other projects) to copy and paste. Here's your
chance to be creative when describing what's changed and why anyone should
care. Don't forget the marketting (but don't overdue it either).
About {{{binindex.xml}}} ... mostly you just put the correct release number
into the XML entities defined at the top. For interrum releasees, update
{{{tapestry-current-release}}}. For the very infrequent stable releases (i.e.,
for a 3.1 or 3.2 final release, a rare event) update
{{{tapestry-stable-release}}}.
'''Note:''' I haven't been through this part of the process since jakarta-site2
switched over to Subversion.
= Email the Announcement =
Whew! Send an [ANNOUNCE] email to jakarta-general@xxxxxxxxxxxxxxxxxx and
tapestry-user@xxxxxxxxxxxxxxxxxxx Use the same (or similar)
text to the news item. Get a beer!
---------------------------------------------------------------------
To unsubscribe, e-mail: tapestry-dev-unsubscribe@xxxxxxxxxxxxxxxxxx
For additional commands, e-mail: tapestry-dev-help@xxxxxxxxxxxxxxxxxx