To prepare a release:
- As soon as you become the release manager: review the goals for the release on the Parrot roadmap (https://trac.parrot.org/parrot/roadmap) and announce the tasks to the Parrot mailing list. Make sure everyone knows what they've committed to accomplish in time for the release.
- Right after the release preceding your release, it is a good idea to start tracking parrot news in NEWS. A good resource are the reports in the weekly #parrotsketch IRC-meeting. A reliable log of these meetings is available in http://irclog.perlgeek.de/parrotsketch/.
- A couple of weeks in advance: Ask people to run
make fulltestand report (and hopefully fix!) any problems they find. Check in with language project leads for 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.
- In the course of the release 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
Make sure your 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
firstname.lastname@example.org your SSH keys as attachments. Without the key you won't be able to ship the release.
Set up your account on http://www.parrot.org/. Any previous release manager may be able to help you, but you may also need to open a support ticket at
email@example.com order to be added to the
parrotgroup has permissions to create the new directories needed to hold documentation for new releases.
- A couple of days in advance: announce the new release to
firstname.lastname@example.org 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 NEWS, CREDITS, PLATFORMS, RESPONSIBLE_PARTIES, api.yaml and https://trac.parrot.org/parrot/wiki/Languages.
- On the Saturday before a release you should notify other developers to stop committing non-release related code to trunk. 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.
- 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.
- NOTE: Build a recent version of Parrot to have available during the release to help with bootstrapping. You must have a version of Parrot built and available to you for some of the subsequent steps.
The day of the release has come. Make sure you have the most recent version of the master branch:
git checkout master && git pull --rebase
Also be sure you do not have any local commits that have not yet been pushed out and tested thoroughly. You can check for this with
git log origin/master..
If there is no output from that command, then your local master and the master on origin are in sync.
Update files with version-specific information, but before doing this you should have parrot configured and have run
make with the old version:
tools/release/update_version.plto update the version string in a several files.
perl tools/release/update_version.pl 3.7.0
IMPORTANT: The version change you just effected by running tools/release/update_version.pl effectively invalidates existing generated bytecode. Assuming, as is likely, that you ran
update_version.plin a directory with an existing build, you must next run
make reconfigto clear out this now invalid bytecode. (Note that this script takes care of modifying generated code, so
make bootstrap-opsis no longer necessary for the release process.)
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.
- 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.
- 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:
- Make sure RESPONSIBLE_PARTIES is still accurate.
- Give yourself credit for the release in CREDITS.
- Configure parrot and run
make distro_tests, and either fix what those tests complain about, or fix them so they don't complain.
- If this is a developer release, or there have been no new entries to the PBC_COMPAT file, skip this step.
If this is a supported release, and new entries to PBC_COMPAT have been added since the last supported release, make 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_pbcif necessary, then run
sh tools/dev/mk_native_pbcto 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.
- Make sure everything works:
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.
When all is well, then 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
git commit -a -m "awesome and informative commit message"
Be careful with
git commit -a, it could add files that you do not mean to include. Verify that the contents of your most recent commit look sane with:
If you want you can note the SHA1 from this commit.
git rev-parse master > SHA1_TO_REMEMBER
Update repository on github.
git push origin master
Prepare and test the release tarball. There are two possible approaches:
- 1 Via
make release VERSION=a.b.c
where a.b.c is a version number like
3.6.0. This will create the tarball named parrot-a.b.c.tar.gz. This will automatically avoid including
DEVELOPINGin the release tarball.
Untar parrot-a.b.c.tar.gz into another area.
Make sure everything works:
perl Configure.pl make world html 2>&1 | tee make_world_html.log make fulltest 2>&1 | tee make_fulltest.log
- 2 Via
As an alternative, 5 and 6 above, you may wish to call:
perl Configure.pl make release_check
This target (or, for short,
make relcheck), will prepare the tarballs, copy the .gz tarball to a temporary directory, and then reconfigure, rebuild, retest (through
make test) and rerelease.
Whichever of these two approaches you take, verify that the version is correct and does not contain the suffix
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
Log in to ftp-osl.osuosl.org.
(As noted above, your SSH public key must be added to the list of authorized keys before you can log in.)
If the release is a monthly development release, create a new directory under ~/ftp/releases/devel.
If the release is in the supported series ("Appendix 1 - Upcoming releases") create the new directory in ~/ftp/releases/supported instead.
Copy the different compressed tarballs and the according checksum 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 \ email@example.com:~/ftp/releases/devel/a.b.c/
(Or use whatever tool you prefer.)
When you're finished making changes, run the trigger script to push the changes out to the FTP mirrors.
Check your changes at ftp://ftp.parrot.org/pub/parrot/releases. It should only take a few minutes for the mirrors to sync.
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
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.
Be sure to include the SHA1 sums of the tarballs in the release announcement; They're automatically generated by
Update the website. You will need an account with editor rights on http://www.parrot.org.
- Add a new page for the release announcement with "Create content" -> "Story". There's some additional stuff needed at the top of the page; use one of the old announcements as a guide.
The "<!--break-->" line marks the end of the text that will appear on the front page.
- For the "News" category, select both "Releases" and "News".
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).
- Under "URL path settings" uncheck "Automatic alias" and set the path to news/[year]/Parrot-[release number].
- Under "Publishing options" make sure "Published" and "Promoted to front page" are checked.
- Under "Administer" -> "Site building" -> "URL Redirects", change the URL for "release/current" to the FTP file for the new release (for example, ftp://ftp.parrot.org/pub/parrot/releases/devel/0.8.1/parrot-0.8.1.tar.gz). Also update the URL for "release/developer" or "release/supported" depending on which type of release this is.
- Update docs.parrot.org. Run
make htmlin a release copy of parrot, and save the resources/ and html/ directories created in docs/. ssh into the parrotvm, and in the webroot for docs.parrot.org, expand these into a release directory (e.g. 1.4.0). in <webroot>/parrot, there are symbolic links for latest, supported, and devel. Update the
latestsymlink to point to your new directory. If this is a supported release, also update the
supportedsymlink. Do not delete any old copies of the docs, don't update the other symlinks.
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.)
Publicize the release by publishing the announcement through the following channels (and any others you can think of):
- Send a text email to parrot-dev, parrot-users, perl6-language, perl6-announce, perl5-porters, etc. (Note: perl6-internals is no longer in use, so you don't need to mail that list.) You should also include LWN.net in this mailing; email to
lwnat that domain.
- 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.
- Modify the topic on #parrot, e.g.:
/topic #parrot Parrot 0.4.8 Released | http://parrot.org/
- Update the wiki frontpage at http://trac.parrot.org/parrot/.
- Update the Wikipedia entry at http://en.wikipedia.org/wiki/Parrot_virtual_machine.
- Update the C2 wiki entry at http://c2.com/cgi/wiki?ParrotCode.
Review the milestone for the current release in Trac at https://trac.parrot.org/parrot/roadmap. Close any completed release-related tickets. Edit the milestone to 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.
Add the version to Trac so new bug reports can be filed against the release. https://trac.parrot.org/parrot/admin/ticket/versions.
Make the latest released version the default version for new reports.
Remove any sufficiently old versions listed there.
You're done! Help yourself to a beer, cola, or other celebratory drink.
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.
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://firstname.lastname@example.org.
Versions with a asterisk (*) are supported releases.
- Sep 20, 2011 - 3.8 - soh_cah_toa - Oct 18, 2011 - 3.9* - dukeleto - Nov 15, 2011 - 3.10 - ?? - Dec 20, 2011 - 3.11 - cotto