docs/project/release_manager_guide.pod - The Release Manager Guide.
This guide lays out in detail the steps necessary to prepare, assemble and publish a Parrot release.
RELEASE MANAGER GUIDE
Please ensure you carefully follow each step in the process. As always, please ask for help if you need it.
NOTE: You can use the newish/experimental script auto_release.pl to automate much of his guide (up to section IX):
perl tools/release/auto_release.pl X.Y.Z
Run perldoc on the tool to get more documentation. This tool is new and experimental. Your mileage may vary. Be prepared to do things manually if you have problems with this script.
I. Preparations During the Month Before a Release
As soon as you become the release manager, review any goals for the release. Presently, the best way to determine this is to ask on
#parrotor, alternatively, email a query to the
parrot-devmailing list. If there are goals for the release, please announce them on
parrot-dev. As well, please ensure everyone understands what they've committed to accomplish in time for the release.
Shortly after the release preceding to your release, it is a good idea to start tracking Parrot news in ChangeLog. A good resource is the individual reports posted in the weekly IRC meeting on
#parrotsketch. You may obtain a complete log of these meetings at http://irclog.perlgeek.de/parrotsketch/.
A couple of weeks in advance of the release, ask people to run
make fulltestand report (and hopefully fix!) any problems they discover. Check-in with language project leaders (e.g., Rakudo) for any potential release blockers. This will, hopefully, afford them sufficient time apply any fixes. Also, please ask people to review any issues targeted for the upcoming release at https://github.com/parrot/parrot/milestones/@version@.
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
In order to do this, please ensure 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
email@example.com your public SSH keys as attachments. Without them, you will not be able to ship the release.
Also, set up your account on http://parrot.org/. Any previous release manager should be able to help you, but you may also need to open a support ticket at
firstname.lastname@example.org order to be added to the
parrotgroup has permissions to create the new directories necessary to contain documentation for new releases.
A couple of days in advance, announce the new release to
email@example.com 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 https://github.com/parrot/parrot/wiki/Languages.
On the Saturday before the release, you should notify other developers to stop committing non-release related code to the master branch. This will help to avoid complications. They are, of course, free to commit to branches as much as they want. You may also set the topic in
#parrot, announcing the time you plan to start the release procedure. This will aid the committers.
You may 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: 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 arrived. Please ensure you have checked out the most recent version of the master branch:
git checkout master git pull --rebase
Also, ensure you do not have any local commits which have not yet been pushed and thoroughly tested. You can do so with the following command:
git log origin/master..
If this produces no output, then your local master and the remote master are in sync.
III. Update the Release Version
First, ensure you have configured Parrot (
perl Configure.pl) and ran
make html with the old version of Parrot. Second, save a copy of the entire docs/ directory to some temporary location; you will need them later in Section X below. Next, update files with the following version-specific information.
tools/release/update_version.plto update the version string in several files. For example,
perl tools/release/update_version.pl A.B.C
The version change you just made by running tools/release/update_version.pl did not invalidate existing generated bytecode. Only if you had to update PBC_COMPAT. Assuming you ran it in a directory with an existing build, you must now run
make reconfigto update the version in your config files.
Update the version number, the date, and your name in docs/parrothist.pod.
Update docs/project/release_manager_guide.pod to remove the pending release you're currently building.
Add any other changes which have occurred since the last release. Hopefully, the committers are updating these files as they work. But, if not, then it's probably a good idea to gather the updates weekly rather than wait until the day of the release. All commits since the last release can be see via: git log RELEASE_A_B_C.. --date=short --pretty=%h%x09%ad%x09%an%x09%B
Update release-related information in tools/release/release.json.
You will use this later for the release announcements. There are a few, essential fields which must be updated at each release:
The date of the next release (see Appendix 1).
Enter the date of the Saturday before the next release.
Enter the date part of the link to the wiki page for the next bugday.
The URL of the FTP directory where the Parrot tarball can be found.
Either devel for a regular development release, or supported for a long-term-support release, every 3rd release a year (i.e. 0, 3, 6, 9).
Make sure RESPONSIBLE_PARTIES is still accurate.
Give yourself credit for the release in CREDITS.
Configure Parrot and run
make distro_tests. Then either fix what those tests complain about or fix the tests so they don't complain.
NOTE: You may skip the following step if this is a developer release or if there have been no new entries to PBC_COMPAT.
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. For example,
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 used only in development and are 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 run
sh tools/dev/mk_native_pbcto update the PBC files used in the native PBC tests. Note: You must already have built Parrot for this to work, and this script will reconfigure and rebuild Parrot with various primitive size options. You will need 64-bit multilib or 64-bit and 32-bit, little-endian and big-endian Parrot versions to generate all native_pbc files.
If PBC_COMPAT was not updated and you got no updated native_pbc files, you need to update the native pbc headers with
perl tools/dev/pbc_header.pl --update-fingerprint t/native_pbc/*.pbc.
Verify that the build process runs smoothly:
make realclean perl Configure.pl --test ... make world installable html 2>&1 | tee make_world_html.log make fulltest 2>&1 | tee make_fulltest.log
Note that running
make fulltesttakes 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
git commit -a -m "awesome and informative commit message"
Be careful with
git commit -a as it could add files you do not mean to include. Verify the contents of your most recent commit look sane with:
If you want, you can note the SHA-1 digest from this commit by running,
git rev-parse master > SHA1_TO_REMEMBER
Update the repository on GitHub with,
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
- 1. Using
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.
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 cd parrot-a.b.c
Verify that the build process runs smoothly:
perl Configure.pl make world installable html 2>&1 | tee make_world_html.log make fulltest 2>&1 | tee make_fulltest.log
- 2. Using
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 use, verify the version is correct and does not contain the suffix
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:
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:
If this is a supported release (see Appendix 1), create the new directory in ~/ftp/releases/supported instead:
For both supported and developer releases, add a symlink from to so that scripts that want to download a Parrot release don't need to guess the location:
cd ftp/releases/all ln -s ../supported/9.9.0 .
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 \ firstname.lastname@example.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:
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 works well 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 the text and the HTML versions.
Please ensure you include the SHA256 sums of the tarballs in the release announcement which are automatically generated by
IX. Update the Website
Update the website. You will need an account with editor rights on http://www.parrot.org.
Create a new page for the release announcement by navigating to going to https://www.parrot.org/node/add/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 both checked.
Under Administer -> Site building -> URL Redirects, change the URL for
release/currentto 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/supporteddepending on which type of release this is.
Update http://docs.parrot.org. Run
make htmlin a release copy of Parrot, and save the resources/ and html/ directories created in docs/. Use SSH to login to
<username>@parrot.organd expand these into a release directory (e.g. 3.8.0) in the webroot (i.e., /var/www/docs.parrot.org/htdocs/parrot) for http://docs.parrot.org. In
<webroot>/parrot, there are symbolic links for
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 and 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.
X. Update parrot.github.com and the Relevant parrot-docsx Repository
To update both the
parrot.github.com and the relevant
parrot-docsx repositories, execute the following command:
perl tools/release/parrot_github_release.pl --docs=[/fullpath/to/old/docs/]
Please note: To review the available options, use the
-h | --help option. In addition, you may also want to review the pod with,
For more information about the update process, see docs/project/release_parrot_github_guide.pod.
Publicize the release by publishing the announcement through the following channels (and any others you can think of):
Send a text email to
parrot-users, etc. You should also include lwn.net in this mailing; email to
lwnat that domain.
Also, notify Perl Weekly at
Submit the announcement story to use Perl, Perl Monks, Slashdot, Newsforge, etc. Don't forget to set a
Followup-To:header, if your mail client lets you.
If you are an IRC op, modify the topic on
#parrot, for example,
/topic #parrot Parrot 4.0.0 "[Name of Parrot Release]" | http://parrot.org/ | Log: http://irclog.perlgeek.de/parrot | #parrotsketch meeting Tuesday 19:30 UTC
If not, ask someone to do this.
Update the Wikipedia entry at http://en.wikipedia.org/wiki/Parrot_virtual_machine.
to prepare the new ChangeLog with the new version number and a skeleton announcement.
You're done! Help yourself to a beer, cola, or other delicious celebratory drink.
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.
To learn more about our support policy, see docs/project/support_policy.pod.
The calendar of releases is available at the
comp.lang.parrot Google calendar, visible at http://email@example.com.
Make sure that at least the next two releases are covered.
- Mar 15, 2016 - 8.2.0 - Util - Apr 19, 2016 - 8.3.0 - rurban - May 17, 2016 - 8.4.0 - Util