avalon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Leo Simons <leosim...@apache.org>
Subject Howto: be a good release manager
Date Sat, 23 Aug 2003 21:22:02 GMT
Based on observation of the latest releases built by Berin and the RC 
process for avalon-components, I did an extensive writeup:


It's also copied below for convenience.

It'd be cool to get everyone who's done releases before (Paul, Berin, 
???) as well as everyone with good ideas and/or questions, to take a 
look and improve on that doc. When we're happy with it, we might even 
consider spamming other projects with it. Plan?



= How to be an Avalon Release Manager =

This howto takes you through the steps of successfully handling the 
avalon release process. Its currently a kind of bulletted no-nonsense 
thing, but anyone should be able to follow.

= Who can be a Release Manager? =

Anyone. You don't even need to be a committer. But you do need someone 
with an account to the relevant machine (currently daedalus.apache.org / 
www.apache.org, will become minotaur.apache.org / www.apache.org / 
cvs.apache.org) to do the actual upload of the releases.

= The process, step by step =

== 1. Get up to speed on the basics ==

you need to know about our technical infrastructure and the tools 
available to you:


Our releases go to http://www.apache.org/dist/avalon/, which is 
organised in accordance to the mandatory
[http://www.apache.org/dev/mirrors.html Mirroring Guidelines] and in 
addition is usuable as a [http://maven.apache.org/ maven] repository. 
You get them there by copying them securely using an SSH client (the scp 
tool in OpenSSH, or SecureFX, or pscp from the putty suite, or any 
number of other clients).

== 2. Get a general sense of subproject direction ==

Is anyone planning a big refactoring of the stuff you want to release? 
What is everyone's opinion on the quality of that material? What do 
people want to do with it? Find the answers to these questions one way 
or another. Usually a mailing list thread will do.

== 3. Get people to accept you as the release manager ==

This is usually not a lot of hassle and subject to lazy consensus, but 
make your intentions known. Can be tied in with item 4 below.

== 4. Draft a release plan ==

Decide on how you want to handle the release process. And write that up. 
You might want to create a stable branch in cvs, use a tracker such as 
jira to assign bugs to a particular release, etc etc. Or you might want 
to not do any of that and simply keep a long list of mailing list thread 
references on a wiki page. But figure that out.

Also, get a general idea of how many release candidates will be 
neccessary, how you will call them and what 'milestones' you will 
associate with those release candidates. Write all that up, but don't 
worry about being overly precise.

=== Release plan example ===

  subject: Avalon-Dagger Release Plan
  to: dev@avalon.apache.org
  from: johndoe@hotmail.com

  Hi gang,

  I would like to get a 1.2 release together for
  Avalon-Dagger in the next month or so. I'm volunteering
  to be the release manager and coordinate that release.

  I will make a release candidate available roughly every
  week at


  until no big blocker issues remain. I will also
  periodically post an overview of the remaining issues to
  the mailing list. I expect to have a
  final release in three weeks from now. Issues will be
  tracked using the wiki; everyone is requested to send
  details of any issues to the development mailing list
  *and* add a link to the relevant thread on the wiki page


  Overview of open issues
  ADAG-123 (Refactor Dagger3 class to be ThreadSafe)
  ADAG-157 (TimedDagger has y2k vulnerability)
  ADAG-149 (Remove JDK-1.4 dependencies)
  ADAG-142 (Proper javadocs on TimedDagger)

== 5. Build Release Candidates ==

We like to name our release candidates ${blah}-${version}-RC#,
where ${blah}-${version} will be the final name of the
distribution and -RC# is the release candidate identifier
(so, for example avalon-dagger-1.2-RC1, avalon-dagger-1.2-RC2,
avalon-dagger-1.2-RC3, etc). However, don't name the
actual distributions like that; give those the final
name (so, avalon-dagger-1.2). Just put them in a place where
it is clear they are release candidates and not final
(ie, http://cvs.apache.org/~johndoe/release-candidates
and *not* http://www.apache.org/dist/avalon/).

To build a release candidate, simply follow the normal build
procedure (a cvs update, a build cleanup, followed by a
distribution build). That may look like:

  cd ~/cvs/avalon/dagger/
  cvs -z3 up -P -d
  maven clean
  maven dist

== 6. Sign the files ==

You need to use GnuPG or a similar tool to sign the releases.
Since many people are not used to PGP signing tools, a lot
more extensive info is at /SigningReleases.

== 7. Tag cvs ==

To keep track of how you built what release and to be able
to reconstruct a particular release candidate later, you should
tag the cvs. This is really simple. Here's a sample command:

  cd ~/cvs/avalon/dagger/
  cvs tag -R Dagger_1_2_a1

you can learn more about the 'tag' command by issueing the

  cvs -H tag

command. In order to make sense out of CVS tags, we follow a
consistent tag format that replaces all '.' and '-' with a
'_' (cvs only allows 0-9A-Za-z_ for tag names, no '.'), starts
with a capital letter, is otherwise lowercase, and replaces
any 'RC#' with either 'a#' or 'b#'. So


are valid examples.

== 8. make the candidate files available ==

Upload the files to your chosen public location. For example:

  cd ~/cvs/avalon/dagger/target/distributions
  ssh cvs.apache.org -c \
    'mkdir -p ~/public_html/avalon/release-candidates/dagger/binaries'
  ssh cvs.apache.org -c \
    'mkdir -p ~/public_html/avalon/release-candidates/dagger/source'
  scp *bin*.zip *bin*.gz *bin*.asc \
  scp *src*.zip *src*.gz *src*.asc \

which are bash (unix/linux/cygwin) commands using OpenSSH. But
you can use graphical tools like SecureFX as well if you like.

== 9. Announce the release candidate ==

Ideally, you can get a team of beta testers to try out every
release candidate to make sure no bugs creep in. Get their
attention by posting an announcement to the user and the
development mailing list.

=== Example Announcement ===

  subject: [ann][Dagger] Release Candidate 1 available
  to: dev@avalon.apache.org, users@avalon.apache.org
  from: johndoe@hotmail.com

  Hi gang,

  A new avalon-dagger-1.2 release candidate (RC1) is up
  for review and comment at


  I'd like all users of these components to test it. I
  would like you all to add all open issues, requests, bug
  reports, etc, relating to these components to this wiki page:


  in addition to sending them to the dev@avalon.apache.org
  mailing list.

  I would like to see everyone interested in helping out
  looking at that page, adding to it, and either committing
  fixes, or submitting patches, depending on cvs karma, of
  course. Thanks for your help in ensuring a quality release!

  A new release candidate will be made available roughly
  weekly until all major issues have been resolved.

  best regards,

  - John Doe

== 10. Rinse and repeat ==

Keep building release candidates until you think your stuff is good to go.

== 11. Call for a PMC vote ==

(Mostly) for legal reasons, the Avalon PMC must vote on all releases. 
Anyone can call for a vote though. If the release process went well, 
this should be mostly a formality. Note that you don't have to be on the 
PMC (or even a committer) to initiate this vote. Note you will always 
need to get a PMC member to administer the vote

=== Example call to vote ===

  subject: [PMC:VOTE] Avalon-Dagger Release
  to: dev@avalon.apache.org, pmc@avalon.apache.org
  from: johndoe@hotmail.com

  Hi gang,

  I'm calling for a vote to make the avalon-dagger
  release candidate that has been up for review and
  commment at


  into a final release. PMC members, please place
  your votes:

  [ ] +1 (for)
  [ ] ±0 (abstain)
  [ ] -1 (against)

  Project Background
  (explain the status of the package, how it has
  changed or not changed recently, a brief overview
  of what it does, etc etc).

== 12. Administer the vote ==

Votes are open for a week, normally (or until
majority is attained). Count and publish the results.

=== Example vote result ===

  subject: [PMC:VOTE-RESULT] Avalon-Dagger Release
  to: dev@avalon.apache.org, pmc@avalon.apache.org
  from: johndoe@hotmail.com

  Hi gang,

  I called for a vote to make the avalon-dagger
  release candidate that has been up for review and
  commment at


  into a final release. The results of the vote are
  as follows:

  [ 10 ] +1 (for)
  [ 3 ] ±0 (abstain)
  [ 2 ] -1 (against)

  Accordingly, the releases will be placed in the
  appropriate location and an announcement will be

== 13. Distribute the files ==

copy the release candidate to the appropriate location
on the distribution server, normally in a subdirectory


for example:

  scp -r cvs.apache.org:~/public_html/avalon/release-candidates/dagger .
  scp -r dagger www.apache.org:/www/www.apache.org/dist/avalon/

== 14. Send the release announcment ==

Wait for 24 hours to allow all the distribution mirrors to
pick up the changes, then send a release announcement. For
major releases, send them to users@avalon.apache.org,
dev@avalon.apache.org and announce@apache.org. For smaller
releases, omit the announce@apache.org address. You may also
want to send the release announcements to news sites such as
theserverside.com, slashdot.org, etc etc.

Also make sure to post the announcement on the website.

=== Example Release Announcement ===

  subject: Avalon-Dagger 1.2 released
  to: dev@avalon.apache.org, users@avalon.apache.org,
  from: dev@avalon.apache.org

  The Avalon team is proud to announce the 1.2 final release of

  Avalon-Dagger is a state-of-the-art IoC container supporting
  advanced features such as Aspect-Oriented Programming,
  Interceptors and an asynchronous event architecture.
  The new 1.2 release provides bugfixes, minor enhancements and
  major new features like hot swapping of components,
  full support for AltRMI remoting, and more.

  You may get the official release from the following URL:


  For more information on Avalon-Dagger, please see


  For more information on the Apache Avalon project, please see


  best regards,

  - The Avalon Development Team

= In summary =


* know your tools (use ant, maven, ssh, scp, gpg and some shell 
scripting to automate everything, as described above)
* don't make a hassle out of the process, just do things and volunteer
* write a plan
* build frequent release candidates
* drink coffee, be patient


# refresh tech skills
# discuss goals
# write release plan, volunteer
# build, and test release candidate
# tag cvs
# sign and deploy release candidate
# announce release candidate
# repeat 4-7 as required, automating as much as possible
# call PMC vote to give a candidate the 'final' status
# deploy release
# send announcements (after 24 hours)
# take a deserved break!


== Release Signing ==

Release signing is not so difficult as it seems. The basics are simple:

* install the right tool
* generate a public/private gpg key (similar but distinct from your SSH 
keypair) using that tool
* add your public key to the KEYS file in the avalon CVS module (using 
copy-paste) and commit it
* use the tool to generate a special signature file for each 
distribution file. That signature can be used to verify that the 
distribution is official (ie it really came from us).

=== 1. Get the right tool ===

I use GnuPG for all my keysigning work. It is a commandline utility 
available for linux, various unixes, windows, and [http://www.cygwin.com 
cygwin]. If you're on linux or you have cygwin, chances are it is 
already installed for you. The windows distribution currently resides at 
ftp://ftp.gnupg.org/gcrypt/binary/, but check http://www.gnupg.org/ for 
the latest files. You should at least glance at the GnuPG manual to get 
yourself started. Its pretty good and easy to follow.

=== 2. Generate your keypair ===

Use the command

  gpg --gen-key

to generate your keys. The console UI is pretty easy to follow. 
Basically, you need to enter some information about yourself that 
uniquely identifies you. Note you only need to generate your key once, 
just like with SSH.

Next, you should generate what is called a *revocation certificate*. 
You'll need that in case your private key is compromised. It is an 
authoritive way to tell others your key has been hacked. Here's how you 
generate it:

  gpg --armor --output revoke.asc --gen-revoke 'Your Name'

where you replace 'Your Name' with the name you entered when you 
generated the key. '--armor' means "give me textual (ASCII) output. 
'--output revoke.asc' means 'save the result in revoke.asc'. 
'--gen-revoke' is the command we give gpg, and 'Your Name' tells gpg 
which key you want to generate the revocation certificate for. Now print 
the generated revoke.asc file, and then erase it (not put it in the 
recycle bin, really erase it). Keep the printed copy in a safe place.

=== 3. Add your public key to the KEYS file ===

Use gpg to export your public key into ascii format, then add that to 
the bottom of the avalon KEYS file:

  gpg --armor --output my.public.gpg.key --export 'Your Name'
  echo >> ~/cvs/avalon/KEYS
  echo my.public.gpg.key >> ~/cvs/avalon/KEYS
  cd ~/cvs/avalon/KEYS
  cvs commit -m 'adding my public gpg key' KEYS

where you replace 'Your Name' with the name you entered when you 
generated the key. The above is mostly the unix version of "copy/paste 
the generated my.public.gpg.key file at the bottom of the KEYS file, 
then commit", but you can use any editor / cvs client to do this.

=== 4. Use the tool to sign the distributions ===

Use gpg to sign the distribution files:

  gpg --armor --detach-sig --output avalon-dagger-1.2.zip.asc 

'--armor' selects ASCII output again. '--detach-sig' tells gpg not to 
scramble the distribution file, but rather to generate a seperate 
signature file. '--output blah' tells gpg to save the result to a file. 
The final argument is the file to sign.

entering this command and then your passphrase every time for every 
distribution file can become cumbersome. I wrote a simple shell script 
that will scan for all releases (it assumes a maven-style build 
structure with distributions in ./target/distributions and jars in 
./target) and generate signatures for all these files. You will have to 
type your private key password for every file. Here's a sample usage:

  cp sign.sh ~/cvs/avalon
  cd ~/cvs/avalon/dagger
  maven clean
  maven dist
  cd ..
  . ./sign.sh

You can find this sign.sh script in avalon-components cvs: 
http://cvs.apache.org/viewcvs.cgi/avalon-components/sign.sh. Using this 
script, you still need to enter your passphrase for every file. Since 
that is very annoying if you have to sign many files, you can 
temporarily disable your private key password. Before doing so, make 
sure your PC is disconnected from any network. Here's how (roughly, make 
sure you read the directions on screen):

     gpg --edit-key 'Your Name'
     > key 1
     > passwd
     <Enter your passphrase>
     > quit

where you replace 'Your Name' with the name you entered when you 
generated your key. 'key 1' tells gpg you want to edit the first key on 
your chain (my wild guess is that you have only one). 'passwd' tells gpg 
that what you want to change for this key is the password. After 
entering your old password, you enter an empty one twice. You'll have to 
confirm that as its a bad idea in general. Confirm, then quit, saving 
your changes.

Now, you can run the sign.sh script. After that, *put your password back 
on the key immmediately*:

     gpg --edit-key 'Your Name'
     > key 1
     > passwd
     <Enter your passphrase>
     <Enter your passphrase>
     > quit

you should be able to guess what the above means. After you've 
reinstated the password protection, you can reconnect your computer.

=== That's it ===

Not that difficult at all, is it? :D

To unsubscribe, e-mail: dev-unsubscribe@avalon.apache.org
For additional commands, e-mail: dev-help@avalon.apache.org

View raw message