Skip to main content

How to Release Bugzilla

This document describes the entire process of releasing a version of Bugzilla. The sections are in order of how things should be done.

Table of Contents

Release Planning

This is where we plan to have a release, long before the actual release is done.

File Bugs

File bugs for the following things...

  1. "Release Bugzilla X.YY, Z.AA" and mark it as severity "blocker." It should block bug 286269, which has the alias bz-release. (Sample: bug 286271)
  2. Status Update: Make it block the first bug. (Sample: bug 286275)
  3. Download page: Make it block the first bug. (Sample: bug 286276)
  4. Changes page: Make it block the first bug. (Sample: bug 286277)
  5. Release/News Announcement: Make it block the first bug. (Sample: bug 286281)
  6. The Release Info page: Make it block the first bug. (Sample: bug 287544)
  7. Security Advisory: It should block the first bug, and and Security bugs targeted at this release should be dependencies. (Sample: bug 290249)
  8. Release Notes: Point releases and rc1 versions need release notes. Each version being released needs a separate Release Notes bug filed. These bugs should block the first bug. For final releases of major versions, you need a "clean up release notes" bug. (Sample: bug 286274)
  9. New Features Page (Release Candidates and Final Releases Only): Make this bug depend on the appropriate Release Notes bug. (Sample: bug 286278)

Motivate People

Basically, just make it really easy to find and access all the bugs that need to be fixed for the release. I usually do this a few days after I file the above bugs.

This means:

  1. Do a search for blockers for the release, and make the query link into a tinyurl. When creating a tinyurl, make sure that no "order by" information is part of the URL so that you don't break people's LASTORDER cookies.
  2. Put that tinyurl at the very end of the topic line of the #mozwebtools IRC channel on irc.mozilla.org, with a brief explanation like "2.20 Blockers: tinyurl".
  3. Send out an email to developers@bugzilla.org explaining that we're releasing, and include the tinyurl. Having just one link in the email gets people to focus a bit more.
  4. If you are desperate: Send out an email to support-bugzilla with a tinyurl pointing to all bugs targeted at your release, sorted by Importance. Explain that you'd like some help, and link them also to the Contributor's Guide

Pre-Release

Basically, you just have to get all the bugs to have patches with review+ on them. A few of them require some special handling:

Security Advisory

Format

The actual "issues" in a security advisory normally look something like this:

Class:       Cross-site scripting
Versions:    2.15 through 2.18rc3 and 2.19.1 (from cvs)
Description: It is possible to blah blah blah...
             And here are some details on how it can be made less bad...
Reference:   https://bugzilla.mozilla.org/show_bug.cgi?id=272620
CVE Name:    CAN-2004-1061

The different values for Class can be found in older Security Advisories. The "CVE Name" is, obviously, not always needed.

Determining Affected Versions

It also can be a bit tricky to determine the earliest version affected by a security bug. What I do is use Bonsai's "blame" interface to find the place where the patched code was first introduced. (That is, the code the Security bug is modifying.) Then, by looking at the cvs log in Bonsai, you can match that up with the dates on the Release Information page.

Getting it Reviewed

Security Advisories get sent to security@bugzilla.org for review. Allow at least two or three days for the members of the list to respond.

If you don't get a response after three or four days, that probably means the advisory is fine. But still check with people on IRC and get them to look at it.

Release Notes

The actual process of writing Release Notes is described in the Release Noting Guide. The important thing to remember about Release Notes is that they should be sent to reviewers@bugzilla.org for comment. Give the list about two days to respond.

They should also be attached normally to the bug, and you should ask some Documentation reviewer to look over them.

Right Before Release

Releasing Bugzilla takes a long time. I think the fastest I ever did it was six hours. Start the process a day or two before you actually want to release.

Web Site Updates

  1. Check-out a copy of bugzilla.org from CVS, to apply your patches to. The best place to do this is on landfill, because it already has the environment set up to do it. Make sure you have checkin access on cvs.mozilla.org.

    The CVS info is:

    CVSROOT=:ext:user%domain.com@cvs.mozilla.org:/www
    cvs -z3 checkout bugzilla-org

    Or, if you don't have checkin access, but you want to work on the web site updates anyhow, the CVSROOT for anonymous access is:

    CVSROOT=:pserver:anonymous@cvs-mirror.mozilla.org:/www

  2. Create a directory for the Security Advisory. The directory is always numbered by the lowest unfixed version that is being fixed. For example, if you release versions 2.16.9, 2.18.1, and 2.19.3, and they all have a single Security Advisory, the security advisory goes into the 2.16.8/ directory.
  3. For each new release, create a "Release Info" page:
    • Create a directory in the releases/ directory for the new release.
    • Copy over the index.html.tmpl file from the previous release on that branch.
    • Edit any links to point to the right place for the new version.
    • Change any text that refers to the previous version to instead refer to this version. This includes at least the title and the text at the top.
    • For Text Release Notes (before Bugzilla 3.0): Put the Release Notes into HTML format. (Sample) You will have to HTML-escape the text Release Notes, and also remove any "%" characters (because they otherwise might confuse Template Toolkit.) You can use the following command to do that:

      perl -MCGI::Util -pe '$_ = CGI::Util::simple_escape($_); $_ =~ s/%/&#37\;/g' < docs/rel_notes.txt > release-notes.html

      For HTML Release Notes (Bugzilla 3.0 and above): Open Firefox and go to the branch installation on landfill. Open up the release notes and save them as "Web Page, complete"--this will make all relative links into absolute links so that you can copy the page to the website. Just remove the Bugzilla page header and page footer, and you can pase the code basically directly as the Release Notes page.

      Do make sure that the docs_urlbase parameter on the branch installation points to the correct docs on bugzilla.org first, though.

    • Link to the appropriate new Security Advisory.
  4. Update the index.html.tmpl in the /releases/ directory.
  5. Put the Status Update into the /status/ directory, dated appropriately. Make sure that you get "Dave's Corner" from justdave.
  6. Update the index.html.tmpl in the /status/ directory to point to the new Status Update.
  7. Patch the /status/changes.html.tmpl to reflect the new releases. If the patch has a "FIXME" date in it, remember to fix it!
  8. Post the News announcement in /news/.
  9. Update the main index.html.tmpl to point to the new News item, and remove the last News item from being listed on the main page.
  10. Now actually put the Security Advisory into the directory. You could have done this earlier, but it usually takes a while to get the Security Advisory complete and reviewed, so I put it last, here.
  11. Update security/index.html.tmpl to include a link to the new Security Advisory.
  12. Update docs/index.html.tmpl to display the latest version numbers for the links to the docs.

And now you should be done with the web site update! Don't check in your changes to CVS yet -- that comes later.

Check-In Security Bugs

Locate approved patches on Security bugs, and check them in now to CVS. If the person who wrote the patches is around, have them do it.

Once you hit this point, you are committed to releasing, because you've essentially exposed Security bugs publically without a release that fixes them.

Freeze the Tree

This is only here so that you remember to do it. Basically, just make sure that from this point until after you post the tarballs, there aren't any checkins to any branch, from anybody but you.

Update Version Numbers

For each branch that you are releasing:

  1. Update Bugzilla/Config.pm's VERSION variable (or Bugzilla/Constants.pm's BUGZILLA_VERSION variable, in more modern versions).
  2. Update docs/xml/Bugzilla-Guide.xml. bz-ver, bz-date, and bz-nextver need to be updated.

Tag the Releases in CVS

You need to create CVS tags for each new release, and move the -BRANCH and _Stable tags. Remember, for each tag that you're going to move, you need to:

  1. Update to that tag.
  2. Delete the tag.
  3. Update to the release tag.
  4. Create that tag.

That's to make sure that you actually remove the tag even from deleted files.

Here's an example series of commands that would be used to tag the 2.18.1, 2.19.3, and 2.16.9 releases:

cd /var/www/html/mkanat218/
cvs update -dP -rBUGZILLA-2_18-BRANCH -C
cvs tag -FR BUGZILLA-2_18_1

cvs update -dP -rBUGZILLA-2_18-STABLE
cvs tag -R -d BUGZILLA-2_18-STABLE
cvs update -dP -rBUGZILLA-2_18_1
cvs tag -FR BUGZILLA-2_18-STABLE

cvs update -dP -rBugzilla_Stable
cvs tag -R -d Bugzilla_Stable
cvs update -dP -rBUGZILLA-2_18_1
cvs tag -FR Bugzilla_Stable

cd /var/www/html/mkanat216/
cvs update -dP -rBUGZILLA-2_16-BRANCH -C
cvs tag -FR BUGZILLA-2_16_9

cvs update -dP -rBUGZILLA-2_16-STABLE
cvs tag -R -d BUGZILLA-2_16-STABLE
cvs update -dP -rBUGZILLA-2_16_9
cvs tag -FR BUGZILLA-2_16-STABLE

cd /var/www/html/checkinmkanat/
cvs update -dP -CA
cvs tag -FR BUGZILLA-2_19_3

For this release, 2.18 was the most current stable series, 2.19 was the development series, and 2.16 was the "old stable" series.

Create the Tarballs

First, wait about 5 minutes after you do the CVS tags. This is because tarballs are pulled from cvs-mirror.mozilla.org, and you need to wait for that server to be updated with the tags.

Now, there's a script for building Bugzilla tarballs. mkanat@bugzilla.org has the latest version, usually.

Just build a tarball for each release, using the version-specific CVS tags that you made above. (Don't use the -BRANCH or _Stable tags.)

Make the Diff Files

In addition to tarballs, you also need to generate the .diff files. For this, you'll need an unpacked tarball of every Bugzilla release from each series you're releasing against.

There's a script called makediffs.pl that you can probably get from mkanat@bugzilla.org. You have to edit it and make a new version for each branch that you're releasing against.

Development versions don't need .diff files, and neither do Release Candidates.

Update the Checksetup Tinderbox

There is a tinderbox that lives on landfill.bugzilla.org for testing checksetup.pl's upgrade ability. It does this by having a copy of a populated database from every version.

When you make a new release, you need to copy the "_branch" or "_tip" database to a database named after the release.

For example, for the 2.18.1 and 2.19.3 release, I did this:

mysqlclone bugs_tip bugs_2_19_3
mysqlclone bugs_bugzilla2_18_branch bugs_2_18_1

I didn't make a 2.16.9 database, because 2.16.9 had no updates to checksetup.pl (so it wasn't any different from 2.16.8, which I already had a database for).

Then the /var/www/html/checksetup/test-checksetup.pl file also needs to be updated. Find the DB_LIST variable and add the new databases to it. (The format of the variable is obvious once you see it.)

Release

Post the Files

Upload the tarballs and .diff files to stage.mozilla.org, to the /pub/webtools directory.

Remember to fix the bugzilla-LATEST and bugzilla-STABLE symlinks, if necessary.

Check-In the Website Updates

Now, you commit the changes you made to the website, above. Double-check everything to make sure that all the dates and times are correct anywhere that you had to put a date/time.

Send Security Advisory

Double-check the Security Advisory before you send it. Make sure that any links you have in the Advisory actually work.

Usually, we GPG sign the Security Advisory with a key that has its public half available from either public keyservers or the bugzilla.org website.

The Security Advisory is sent to:

  • BugTraq
  • announce@bugzilla.org
  • support-bugzilla@lists.mozilla.org

Send each as a separate email. This is because you will get a lot of bounce messages, and you don't want them to be spread around to the other lists. (Some things sending bounce messages are really stupid and will attempt to do this.)

Send Release Announcement

This is the Release Announcement that you created on the bug that you filed.

Make sure that you put [ANN] at the beginning of the Subject line.

Send it to:

  • announce@bugzilla.org
  • support-bugzilla@lists.mozilla.org

Once again, send each as a separate email.

Post-Release

Stuff you do after you've posted the release and sent the announcements:

  1. Unlock the Security Bugs. Just remove them from the webtools-security group.
  2. Update the Version Trackers:
  3. Update the VERSION number in Bugzilla/Config.pm on the tip, to have a "+" after it.
  4. Update bugzilla-update.xml on landfill so that the notification system will detect new releases.
  5. If needed, update Bundle::Bugzilla to have the right version numbers and modules for the latest stable release.