Release Instructions

To prepare a release:

0.

Announce the new release to parrot-porters@perl.org and to the IRC channel #parrot at least a couple days in advance. Ask whether there are any showstopping bugs. It's also good to ask for updates to NEWS, CREDITS, PLATFORMS, RESPONSIBLE_PARTIES and LANGUAGES_STATUS.

You might also select a name for your release. For example, you could select a name from http://en.wikipedia.org/wiki/List_of_parrots.

1.

Make sure you're up to date:

 $ svn update

You may want to ask the developer base to stop committing big changes; it will avoid complications. Or you could create a release branch, make release-related changes there, and fold them back into the trunk once the release is done. This process is explained in Appendix 1.

2.

Update files with version-specific information:

a

Increment the version number in the following files: VERSION, parrot.spec, MANIFEST.generated, META.yml, README.

Note: Source0 in parrot.spec might have to be adapted as well.

Also update the version number, date, and your name in the the file: docs/parrothist.pod.

Update this file, that is release_manager_guide.pod, to remove the pending release you're in the middle of.

b

Update ChangeLog, NEWS 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 monthly release.

c

Update release-related information in tools/util/release.json. This will be used later when making release announcements. There are a few essential fields that must be updated at each release:

release.*

The date of the next release is in Appendix 2.

bugday.date

Enter the date of the Saturday before the next release.

rt.tracking

Create a new RT-ticket for the next release. Please use the release month in the ticket, and *do not* use the release number. Releases are date-based, while release numbers are feature-based. Project team members agree on the release number near the actual release, based on the features available in trunk at the time. Mark the ticket for the next release as dependent on the current release. Change the URL fragment in rt.tracking to use the number of the ticket for the next release.

wiki.bugday

Update the date part of the link to the wiki page for the next bugday.

d

Make sure RESPONSIBLE_PARTIES is still accurate.

e

Give yourself credit for the release in CREDITS.

f

Configure parrot and run make distro_tests, and either fix what those tests complain about, or fix them so they don't complain.

g

Run perl tools/dev/pbc_header.pl --upd t/native_pbc/*.pbc to update version and fingerprint in the native tests. Please check with prove t/native_pbc/*.t.

NOTE: Due to frequent PBC changes, these tests are currently skipped.

h

Make sure everything works:

 $ make realclean
 $ perl Configure.pl --test ...
 $ make world docs html 2>&1 | tee make_world_docs_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.

3.

When all is well, then commit your changes:

 svn diff | more
 svn commit

Write down the revision number from this commit. You will need it later in step 7.

4.

Prepare the release tarball.

 $ make release VERSION=a.b.c

where a.b.c is the version number. This will create the tarball named parrot-a.b.c.tar.gz. This will automatically avoid including DEVELOPING in the release tarball.

5.

Untar parrot-a.b.c.tar.gz into another area.

6.

Make sure everything works:

 $ perl Configure.pl
 $ make world docs html 2>&1 | tee make_world_docs_html.log
 $ make fulltest        2>&1 | tee make_fulltest.log

7.

Tag the release as "RELEASE_a_b_c", where a.b.c is the version number. If you're working in trunk, be sure to specify the revision number generated in step 3, above.

 $ export SVNPARROT=https://svn.perl.org/parrot
 $ svn copy -m "tagged release a.b.c" \
   $SVNPARROT/trunk $SVNPARROT/tags/RELEASE_a_b_c

See also Appendix 1 below.

8.

In PAUSE, assign yourself co-maintainer permissions on all modules owned by PARROTRE.

Upload to CPAN.

NOTE: you may get a failure message from the CPAN Indexer about the content of META.yml. Don't panic, the tarball still uploaded okay. You do need to fix META.yml for the next release. Under "no_index" list any modules that aren't properly part of the Parrot distribution.

Once you get a reply from the PAUSE indexer, log in to PAUSE to clean up module permissions. Under "View Permissions" search for your PAUSE ID. Any new modules added in this release will list your PAUSE ID as the "owner". Change the owner to PARROTRE.

See docs/project/pause_guide.pod for more details.

9.

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

  $ ./parrot tools/util/crow.pir --type=text
  $ ./parrot tools/util/crow.pir --type=html

Take the screen output and paste it into the application you need. HTML works well for use Perl and PerlMonks, and text for the rest. It is not a bad idea to add a "highlights" section to draw attention to major new features, just be sure to say the same thing in both text and HTML versions.

10.

Update the website. The svn repository for the website is at https://svn.perl.org/perl.org/docs/live/parrotcode.

a

Add the release announcement to news/[year]/Parrot-[release].html. There's some additional stuff needed at the top of the file; use one of the old announcements as a guide.

b

Update the top-level index.html page. (The old mini-announcement may be commented out).

c

Update /.htredirects to point to the proper CPAN URL.

If you have commit privs to the parrotcode repository, be sure to test locally in combust before committing. Otherwise, make the changes in your working copy and send a patch to webmaster@parrotcode.org.

11.

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

a

Send a text email to parrot-porters, perl6-language, perl6-announce, perl5-porters, etc. You should also include LWN.net in this mailing; email to lwn at that domain.

b

Submit the use Perl 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.

c

Modify the topic on #parrot, e.g.:

 /topic #parrot Parrot 0.4.8 Released | http://parrotcode.org/

d

Update the wiki frontpage at http://www.perlfoundation.org/parrot/index.cgi?parrot. Update the next planned release date on the wiki at http://www.perlfoundation.org/parrot/index.cgi?release_schedule_2008.

e

Update the Wikipedia entry at http://en.wikipedia.org/wiki/Parrot_virtual_machine.

12.

Close any release-related tickets in RT. If they are not yet resolved, migrate the critical ones to the next milestone release ticket. Non-critical unresolved tickets can be simply unlinked.

13.

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

ABOUT THIS DOCUMENT

This document was written after a couple of subtly incorrectly assembled releases--usually when someone forgot to delete DEVELOPING (which is now automated!), but at least once where the MANIFEST check failed. The intent of this file is to document what must be done to release so that such mistakes won't happen again.

SEE ALSO

README, RESPONSIBLE_PARTIES.

Appendix 1 - Releasing from a branch

Instead of step 1, create a new branch, and get a working copy of it:

   $ export SVNPARROT=https://svn.perl.org/parrot
   $ svn copy -m"Starting release a.b.c" \
              $SVNPARROT/trunk $SVNPARROT/branches/RELEASE_a_b_c
   $ svn checkout $SVNPARROT/branches/RELEASE_a_b_c parrot-release
   $ cd parrot-release

Make a note of the revision number produced by svn copy so that you know which changes were made on the branch.

This new parrot-release working copy will be "on" the branch, insulated from trunk commits, so you should feel free to announce the end of any "code slush" that may be in effect.

Then, do steps 3 through 7 using your branch working copy, so that commits go to the branch. When you are sure that the tarball is all that it should be, tag the release as a copy from the branch (instead of the trunk):

   $ svn copy -m"Release a.b.c" \
           $SVNPARROT/branches/RELEASE_a_b_c $SVNPARROT/tags/RELEASE_a_b_c

Alternatively you can also move the branch:

   $ svn move -m "Tagging release a.b.c" \
           $SVNPARROT/branches/RELEASE_a_b_c $SVNPARROT/tags/RELEASE_a_b_c

Upload your shiny new tarball, announce the release, and close tickets (steps 9 through 11) as described above.

Finally (don't get your celebratory drink yet!), you need to merge the branch changes back into the trunk. To do this, you need an up-to-date working copy on the trunk. You can reuse the parrot-release working copy via svn switch by switching it back to the trunk (assuming parrot-release is the current directory):

   $ svn switch $SVNPARROT/trunk

Then, merge the branch changes back into it:

   $ svn merge -r 12345:HEAD $SVNPARROT/branches/RELEASE_a_b_c

where "12345" is the revision number of the svn copy operation that created the branch. Check that the merge was clean, "make test" if there were any code changes on the branch, and commit. Then go get that beer!

Appendix 2 - Upcoming releases

To make a monthly release schedule possible, we're spreading the burden of releases across multiple release managers. Releases are scheduled for the 3rd Tuesday of each month. Version numbers for each release will be determined each month, and will depend on the features actually present in that release.

 - September 16th, 2008 - Patrick R. Michaud
 - October 21st, 2008   - Jerry Gay
 - November 18th, 2008  - chromatic
 - December 16th, 2008  - Andrew Whitworth