RELEASE MANAGER GUIDE

The need for this document arised after a couple of improperly assembled releases. The intent of this guide is to describe what must be done to prepare for a release so that such mistakes won't happen again.

I. Preparations During the Month Before a Release

  1. As soon as you become the release manager, review the goals for the release on the Parrot roadmap (http://trac.parrot.org/parrot/roadmap) and announce the tasks to the parrot-dev mailing list. Make sure everyone knows what they've committed to accomplish in time for the release.
  2. Right after the release preceding your release, it is a good idea to start tracking Parrot news in ChangeLog. A good resource are the individual reports posted in the weekly IRC meeting on #parrotsketch. A complete log of these meetings is available at http://irclog.perlgeek.de/parrotsketch/.
  3. A couple of weeks in advance, ask people to run make fulltest and report (and hopefully fix!) any problems they find. Check in with language project leaders (e.g. Rakudo) for potential release blockers to allow time to fix them. Also ask people to review the tickets targeted for the upcoming release (https://trac.parrot.org/parrot/roadmap).
  4. During the course of the release process, you will need to be able to log in and operate on two different servers. To oversimplify a bit, you will need to be able to execute these two commands and their scp equivalents.
    • ssh parrot@ftp-osl.osuosl.org

      • Make sure your public SSH key(s) have been added to the FTP server ftp-osl.osuosl.org. You can open a support ticket for this by sending an email to support@osuosl.org with your public SSH keys as attachments. Without them, you won't be able to ship the release.

    • ssh <username>@parrot.org

      • Set up your account on http://parrot.org/. Any previous release manager may be able to help you but you may also need to open a support ticket at support@osuosl.org in order to be added to the parrot group. The parrot group has permissions to create the new directories needed to hold documentation for new releases.

  5. A couple of days in advance, announce the new release to parrot-dev@lists.parrot.org and to the IRC channel #parrot. Ask whether there are any showstopping bugs. Check in again with the language project leads. It's also good to ask for updates to ChangeLog, CREDITS, PLATFORMS, RESPONSIBLE_PARTIES, api.yaml and http://trac.parrot.org/parrot/wiki/Languages.
  6. On the Saturday before a release, you should notify other developers to stop committing non-release related code to the master branch. This will help avoid complications. They are of course free to commit to branches as much as they like. You might also set the topic in #parrot, announcing the time when you plan on starting the release procedure. This will help the committers with timing their last minute commits.
  7. You might also select a name (and optionally a quote) for your release. For example, you could select a name from http://en.wikipedia.org/wiki/List_of_parrots.
  8. NOTE: You must have a recent version of Parrot already built for some of the subsequent steps.

II. Get the Most Recent Changes

The day of the release has come. Make sure you have the most recent version of the master branch checked out:

    git checkout master
    git pull --rebase

Also, make sure you do not have any local commits that have not yet been pushed and tested thoroughly. You can do so by running:

    git log origin/master..

If there is no output from that command, then your local master and the remote master are in sync.

III. Update the Release Version

Update files with version-specific information but before doing so, you should already have configured Parrot (perl Configure.pl) and ran make with the old version.

  1. a
    Use tools/release/update_version.pl to update the version string in several files: 
      perl tools/release/update_version.pl 3.8.0
    IMPORTANT: The version change you just made by running tools/release/update_version.pl invalidates any existing generated bytecode. Assuming that it was run in a directory with an existing build, you must now run make reconfig to clear out any invalid bytecode.
    c
    Update the version number, date, and your name in docs/parrothist.pod.
    d
    Update this file (docs/project/release_manager_guide.pod) to remove the pending release you're currently building.
  2. Update ChangeLog with the new version number and any other changes that have occurred since the last release. Hopefully, these files are being updated as committers work. If not, it's probably a good idea to gather the updates weekly rather than waiting until the day of the release.
  3. Update release-related information in tools/release/release.json. This will be used later when making release announcements. There are a few essential fields that must be updated at each release:
    4. release.*
    The date of the next release (see Appendix 1).
    bugday.date
    Enter the date of the Saturday before the next release.
    wiki.bugday
    Enter the date part of the link to the wiki page for the next bugday.
    ftp.path
    The URL of the FTP directory where the Parrot tarball can be found.
  4. Make sure RESPONSIBLE_PARTIES is still accurate.
  5. Give yourself credit for the release in CREDITS.
  6. Configure Parrot and run make distro_tests. Then either fix what those tests complain about or fix the tests so that they don't complain.
  7. NOTE: You may skip the following step if this is a developer release or there have been no new entries to PBC_COMPAT.

    8. If this is a supported release and new entries to PBC_COMPAT have been added since the last supported release, add a new entry with a new major version number for this release at the top of the list:

      3.0     2007.10.17      coke    released 0.4.17

    Delete all minor version numbers since the last major bytecode version number as these are only used in development and not relevant to the bytecode support policy. Those changes are all included within the major version number increase for the supported release.

    Once you've updated PBC_COMPAT - running sh tools/dev/mk_packfile_pbc if necessary - then run sh tools/dev/mk_native_pbc to update the PBC files used in the native PBC tests. Note that you must have Parrot already built for this to work and that this script will reconfigure and rebuild Parrot with various primitive size options.

  8. Verify that the build process runs smoothly:
    9.     make realclean
    perl Configure.pl --test ...
    make world html 2>&1 | tee make_world_html.log
    make fulltest   2>&1 | tee make_fulltest.log

    Note that running make fulltest takes a while and that separate harnesses are being run.

IV. Push Changes to the GitHub Repository

When all is well, commit your changes:

    git diff
    git add file1 file2 ...
    git commit -m "awesome and informative commit message"

Instead of adding files individually, you can also tell git commit that you want all modified and deleted files to be in your next commit via the -a switch:

    git commit -a -m "awesome and informative commit message"

Be careful with git commit -a as it could add files that you do not mean to include. Verify that the contents of your most recent commit look sane with:

    git show

If you want, you can note the SHA-1 digest from this commit by running:

    git rev-parse master > SHA1_TO_REMEMBER

Update repository on GitHub:

    git push origin master

V. Prepare the Release Tarballs

There are two possible approaches to preparing and testing the release tarball: using make release or using make release_check.

1 Via make release
a
Begin by running: 
    make release VERSION=a.b.c
where a.b.c is the version number (e.g. 3.8.0). This will create the tarball named parrot-a.b.c.tar.gz. The DEVELOPING file is automatically excluded from the release tarball.
b
Extract parrot-a.b.c.tar.gz into another directory: 
    cp parrot-a.b.c.tar.gz ~/another/directory
    cd ~/another/directory
    tar -xvzf parrot-a.b.c.tar.gz
c
Verify that the build process runs smoothly: 
    perl Configure.pl
    make world html 2>&1 | tee make_world_html.log
    make fulltest   2>&1 | tee make_fulltest.log
2 Via make release_check
As an alternative, you can package the release by running: 
    perl Configure.pl
    make release_check
This target (or, for short, make relcheck), will prepare the tarball, copy it into a temporary directory, and then reconfigure, rebuild, re-test (with make test) and re-release.

Whichever of these two approaches you take, verify that the version is correct and does not contain the suffix devel:

    ./parrot -V

VI. Tag the Release Commit

Tag the release as "RELEASE_a_b_c", where a.b.c is the version number:

    git tag RELEASE_a_b_c
    git push --tags

VII. Push Tarballs to the FTP Server

Log in to ftp-osl.osuosl.org:

    ssh parrot@ftp-osl.osuosl.org

As mentioned previously, your public SSH key must be added to the list of authorized keys before you can log in.

If this is a development release, create a new directory under ~/ftp/releases/devel:

    mkdir ~/ftp/releases/devel/a.b.c

If this is a supported release, (see Appendix 1), create the new directory in ~/ftp/releases/supported instead:

    mkdir ~/ftp/releases/supported/a.b.c

Copy all the tarballs and their respective digest files from your machine into the new directory:

    scp parrot-a.b.c.tar.gz \
        parrot-a.b.c.tar.bz2 \
        parrot-a.b.c.tar.gz.sha256 \
        parrot-a.b.c.tar.bz2.sha256 \
        parrot@ftp-osl.osuosl.org:~/ftp/releases/devel/a.b.c

You don't necessarily have to use scp for this step. You can use whichever tool you prefer.

When you're finished making changes, run the trigger script to push the changes out to the FTP mirrors:

    ~/trigger-parrot

Verify your changes at ftp://ftp.parrot.org/pub/parrot/releases. It should only take a few minutes for the mirrors to sync.

VIII. Release Announcement

Compose the release announcement. Use tools/release/crow.pir to make this part easier. You can specify the format of your announcements like so:

    ./parrot tools/release/crow.pir --type=text
    ./parrot tools/release/crow.pir --type=html

Copy the output and paste it into the application you need. HTML works well for Perl and PerlMonks, and text for the rest. It's a good idea (although not necessary) to add a "highlights" section to draw attention to major new features. If you do, be sure to say the same thing in both text and HTML versions.

Be sure to include the SHA1 sums of the tarballs in the release announcement which are automatically generated by make release.

IX. Update the Website

Update the website. You will need an account with editor rights on http://www.parrot.org.

  1. Create a new page for the release announcement by navigating to Create content -> Story. There's some additional stuff needed at the top of the page; use one of the old announcements as a guide.

    2. The "<!--break-->" line marks the end of the text that will appear on the front page.

  2. For the "News" category, select both "Releases" and "News".

    3. Add tags to the page for significant changes in this release (e.g. "rakudo" for significant Rakudo language updates or "gc" for significant garbage collection subsystem updates).

  3. Under URL path settings, uncheck Automatic alias and set the path to news/[year]/Parrot-[release number].
  4. Under Publishing options, make sure Published and Promoted to front page are both checked.
  5. Under Administer -> Site building -> URL Redirects, change the URL for release/current to the FTP file for the new release (e.g. ftp://ftp.parrot.org/pub/parrot/releases/devel/3.8.0/parrot-3.8.0.tar.gz). Also update the URL for release/developer or release/supported depending on which type of release this is.
  6. Update http://docs.parrot.org. Run make html in a release copy of Parrot, and save the resources/ and html/ directories created in docs/. Use SSH to login to <username>@parrot.org and expand these into a release directory (e.g. 3.8.0) in the webroot for http://docs.parrot.org. In <webroot>/parrot, there are symbolic links for latest, supported, and devel. Update the latest symlink to point to your new directory. If this is a supported release, also update the supported symlink. Do not delete any old copies of the docs and don't update the other symlinks.
  7. Preview the new page, and submit it.

The old release announcement may be edited to uncheck Promoted to front page to keep the main page fresh.

X. Publicity

Publicize the release by publishing the announcement through the following channels (and any others you can think of):

  1. Send a text email to parrot-dev, parrot-users, perl6-language, perl6-announce, perl5-porters, etc. You should also include lwn.net in this mailing; email to lwn at that domain.
  2. Submit the announcement story to use Perl, Perl Monks, Slashdot, Newsforge, etc. Don't forget to set a Reply-To: or Followup-To: header, if your mail client lets you.
  3. Modify the topic on #parrot:
    4.     /topic #parrot Parrot 0.4.8 Released | http://parrot.org/
  4. Update the wiki frontpage at http://trac.parrot.org/parrot/.
  5. Update the Wikipedia entry at http://en.wikipedia.org/wiki/Parrot_virtual_machine.
  6. Update the C2 wiki entry at http://c2.com/cgi/wiki?ParrotCode.

XI. Review the Milestones

Review the milestone for the current release in Trac at http://trac.parrot.org/parrot/roadmap and mark it as Completed. Marking a milestone as Completed will migrate all open tickets to a selected milestone (generally the next milestone). Non-critical tickets can have their milestone unset.

Also make sure to close any completed release-related tickets.

XII. Changes to Trac

  1. Add the latest version to Trac so that new bug reports can be filed against the release. https://trac.parrot.org/parrot/admin/ticket/versions.
  2. Make the latest version the default version for new reports.
  3. Remove any sufficiently old versions listed there.

XIII. Finish

You're done! Help yourself to a beer, cola, or other celebratory drink.

SEE ALSO

README, RESPONSIBLE_PARTIES.

Appendix 1 - Upcoming Releases

To make a monthly release schedule possible, we spread the burden of releases across multiple release managers. Releases are scheduled for the 3rd Tuesday of each month.

The starred releases are Parrot's quarterly supported releases, see docs/project/support_policy.pod.

The calendar of releases is available at the comp.lang.parrot Google calendar, visible at http://www.google.com/calendar/render?cid=ldhctdamsgfg5a1cord52po9h8@group.calendar.google.com.

Versions with an asterisk (*) are supported releases:

    - Oct 18, 2011 - 3.9*  - dukeleto
    - Nov 15, 2011 - 3.10  - ??
    - Dec 20, 2011 - 3.11  - cotto