2.6. Making a release

The purpose of this chapter is to simplify for the person that is actually doing the release work and to make sure that everything is done in the exact same way every time and nothing is forgotten.

It is provided with the hopes of being helpful.

To understand this you need knowledge of how CVS works and how you normally build and test ArgoUML.

This instruction is supposed to work on a windows system (running build.bat). The author (Linus Tolke) has for some time been running it on a Cygwin system (running build.sh) assuming that this will be the same as on any UNIX system. How it is actually run on a Cygwin/UNIX system is also noted.

Here are the steps to be done when one actually does a release:

  1. Tag the whole CVS repository with the freeze tag!

    Normally this tag is "VERSION_X_Y_Z_F", e.g. VERSION_0_9_7_F. The according command line CVS command is cvs rtag VERSION_X_Y_Z_F argouml. (Because of a problem on the Tigris site, this doesn't work. Instead make sure you have a complete checked out copy of ArgoUML, go to the root directory argouml and run the command cvs tag VERSION_X_Y_Z_F.)

  2. These commands assume that you have set the CVSROOT correctly. Make sure it is set to :pserver:user@cvs.tigris.org:/cvs.

  3. Check the key to sign the jar files for java web start.

    This is to make sure that you have a valid key for the purpose of signing the java web start version of the files.

    Since the ArgoUML project and the Tigris organization are loose organizations we cannot buy a "real" key. The keys we use are the unsigned keys that can be generated by anyone using the keytool provided with java.

    A key is generated with the command keytool -genkey -alias argouml -storepass secret.

    By default these keys have a validity of just three (3) months but by giving the -validity days the validity can be extended.

  4. Run the script argouml/tools/bin/build-release.sh and give the answers to the questions.

    This will:

    1. Check out the source in a new directory. The new directory is named after the freeze tag that you give.

    2. Make the ant executable with the command chmod +x ../tools/ant-1.4.1/bin/ant.

    3. Build the release!

      This is done in the argouml/src_new directory of the newly created copy by issuing the command build dist-release! (Linus: It takes around 2 minutes on my machine JDK1.3.1_10/Intel 1400MHz (on batteries)/512MB (February 2004), It takes around 10 minutes on my machine JDK1.3.1_01/Intel 700MHz/256MB (May 2003), It takes around 30 minutes on a Lysator machine simultaneously doing a lot of other things. JDK1.3.1_06/Sun4d/256MB (July 2003). )

      This should create the directory argouml/argouml-VERSION with the files ArgoUML-VERSION-libs.tar.gz, ArgoUML-VERSION-libs.zip, ArgoUML-VERSION-modules.tar.gz, ArgoUML-VERSION-modules.zip, ArgoUML-VERSION-src.tar.gz, ArgoUML-VERSION-src.zip, ArgoUML-VERSION-app.tgz, ArgoUML-VERSION.tar.gz, ArgoUML-VERSION.zip, and index.html. There should also be a subdirectory argouml/argouml-VERSION/jws with .jar and .jnlp files. The .jar files in the subdirectory differ from the jar files in the zip and tar archives in that they are signed using your key.

    4. Run through the automatic tests!

      There are two sets of automatic test cases.

      • The JUnit test cases in argouml/tests are run by issuing the command build alltests in the argouml/src_new directory. (Linus It takes around 10 minutes on my machine JDK1.3.1_10/Intel 1400MHz (on batteries)/512MB (February 2004), It takes around 12 minutes on my machine JDK1.3.1_01/Intel 700MHz/256MB (May 2003), It takes around three (3) hours on a Lysator machine simultaneously doing a lot of other things and the X session over a 50KB/s modem. JDK1.3.1_06/sun4d/256MB (July 2003). )

        There should not be any failed tests. (See details on where to find the result in Section 2.4, “The JUnit test cases”).

      • The JUnit test cases in modules/junit are run by invoking JUnit tests from the Tools menu, specifying the Test Case TestAll, and running without "Reload classes every run" checked in the ArgoUML window that opens. (See details in Section 2.4, “The JUnit test cases”).

        No problems shall be found.

      If the tests did not pass See Section 2.6.1, “The release did not work”.

    5. Build documentation and copy it.

      While connected to the internet you download the docbook-xsl and JimiProClasses.zip. The docboox-xsl is downloaded by issueing the command build docbook-xsl-get. The JimiProClasses.zip is downloaded from Sun. Instructions for this is in the fop README file: argouml/tools/fop-0.20.3/README.

      The PDF versions of the documentation shall be copied from the build/documentation/pdf/*/*.pdf to argouml-version/basename-version.

    6. Upload the files onto the Tigris website!

      A tree with all files is located in argouml-version. This complete tree is uploaded to argouml-upload on the site.

    7. Tag the whole repository with the release tag!

      This tag is "VERSION_X_Y_Z", e.g. VERSION_0_9_7. The according command line CVS command is cvs tag VERSION_X_Y_Z when your are standing in the argouml-directory.

  5. Test the release manually!

    The purpose of this is to make sure that there isn't any problem introduced by the release procedure and that the jar files contains the correct list of jars.

    Either the ArgoUML-VERSION.tar.gz or ArgoUML-VERSION.zip file is tested. Unpack, start using the command java -jar argouml.jar, and do some ad-hoc testing.

    If the tests did not pass See Section 2.6.1, “The release did not work”.

  6. Open the repository for commits towards the next version.

    This is done by setting the argo.core.version in default.properties to Number of next release, committing and telling everyone on the developers mailing list. Notice that this cannot be done in the tagged copy but you either need to go back to your other working tree or need to check out the file argouml/src_new/default.properties specifically to do this.

  7. Go through Issuezilla and check things.

    Things to check are:

    1. That there is a Version created in Issuezilla for the newly created release.

      The purpose of this is to make it possible for everyone to report bugs on the new release.

    2. Make sure that the upcoming releases have target milestones created for them. This needs to be done for all components that has the same release scheme. Also see that the numbering is the same in all components and that it is in the correct chronological order except for the not yet done releases that come before the already completed.

    3. Change the target milestones of all the not yet resolved issues for this release to ---.

    4. Change the target milestones of any fixed issue in component argouml or modules with target milestone --- to that of the current release.

      This is probably some developer that has fixed an issue by forgot to set the target milestone correctly.

    5. Move all issues reported on 'current' to this release (for components argouml and modules).

      These items were reported between the previous version and this version. Since 'current' will be reused for the next release, they need to be locked to the closest release to where they were found.

    6. Reopen RESOLVED/REMIND

      This can also be a good time to change all RESOLVED/REMIND. Search for them and Reopen them.

    7. Check RESOLVED/LATER

      It could also be good to check that all RESOLVED/LATER has a valid target milstone (must be an upcoming milestone). Search for them and Reopen the ones that havn't. Also, if the milestone denotes or is going to be resolved in the upcoming release, Reopen them with a comment that they are now active.

  8. Make announcements!

    Write a News announcements and a short note on the dev, users and announce lists. Announcer should make sure that he/she is already subscribed to all lists with a reference to the news item.

    The announcement shall include a statement on what kind of release this is, information on what has changed (for stable releases this is a list of what has changed since the last stable release), the list of resolved issues, a list of serious known problems with this release (stable releases shouldn't have any), technical details on how the release was built, and the plan for the following release.

    Freshmeat: currently Thierry Lach does the Freshmeat announcements which require a login so just inform him.

2.6.1. The release did not work

This shouldn't happen! This really shouldn't happen!

The reason that this has happened is that one of the developers has made a mistake. You now must decide a way forward.

2.6.1.1. Fix the problem yourself.

If the problem is obvious to you and you can fix it quickly, do so. This is done by doing the following:

  • Make the release tag into a branch

    cvs rtag -b -r VERSION_X_Y_Z_F BRANCH_X_Y_Z

  • Update your checked out copy to be on that branch

    cvs update -r BRANCH_X_Y_Z

  • Fix the problem in your checked out copy

  • Commit the problem in the branch

    cvs commit -m'Fix of problem blabla'

  • Continue the build process

    This is done by restarting the build dist-release-command and from that point on working in the branch instead of at the tag.

  • Explain to the culprit what mistakes he has made and how to fix it.

    It is now his responsibility to make sure that the problem will not appear in the next version. He can do this either by merging in your fix or by fixing the problem in some other way.

    At this point an in-detail description of how poor programming skills the culprit has and how ugly his mother is, is probably in place but please keep it constructive! Remember, you might be mistaken when you guess who the responsible is.

2.6.1.2.  Delay the release waiting for someone to fix the problem.

Create the branch as described in Section 2.6.1.1, “Fix the problem yourself.”. Then tell the culprit and everyone on the developer list what the problem is and that it is to be fixed in the release branch a.s.a.p.

Monitor the changes made to the branch to verify that no one commits anything else but the solutions to the problems.

When you get notified that it is completed, update your checked out copy and continue the release work.