Skip to content
Browse files

Modify on basis of 3.6.0 experience, particularly re server permissio…

…ns, make reconfig, etc. Some POD reformatting.
  • Loading branch information...
1 parent e0231e5 commit 0d3a111dc336a8e0f2dbdd21f3275c2ada9d2520 @jkeenan jkeenan committed Jul 19, 2011
Showing with 128 additions and 76 deletions.
  1. +128 −76 docs/project/release_manager_guide.pod
View
204 docs/project/release_manager_guide.pod
@@ -1,59 +1,93 @@
# Copyright (C) 2007-2011, Parrot Foundation.
-=head1 Release Manager Guide
+=head1 RELEASE MANAGER GUIDE
To prepare a release:
+=head2 I. Preparation during Month before Release
+
=over 4
-=item 0.
+=item 1
As soon as you become the release manager: review the goals for the release on
the Parrot roadmap (L<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.
+=item 2
+
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 L<http://irclog.perlgeek.de/parrotsketch/>.
+=item 3
+
A couple of weeks in advance: Ask people to run C<make fulltest> and
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
L<https://trac.parrot.org/parrot/roadmap>.
-Make sure your ssh key have been added to the FTP server ftp-osl.osuosl.org.
+=item 4
+
+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 C<scp> equivalents.
+
+=over 4
+
+=item * C<ssh parrot@ftp-osl.osuosl.org>
+
+Make sure your SSH key(s) have been added to the FTP server
+C<ftp-osl.osuosl.org>. You can open a support ticket for this by sending an
+email to C<support@osuosl.org> with your SSH keys as attachments.
Without the key you won't be able to ship the release.
-Set up your account on L<http://www.parrot.org/> and ask an previous release
-manager to provide you with editor privileges if you don't already have them.
-Any previous release manager should be able to help.
+=item * C<ssh E<lt>usernameE<gt>@parrot.org>
+
+Set up your account on L<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 C<support@osuosl.org> in order to be added to the C<parrot> group.
+The C<parrot> group has permissions to create the new directories needed to
+hold documentation for new releases.
+
+=back
+
+=item 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
+C<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 F<NEWS>, F<CREDITS>,
F<PLATFORMS>, F<RESPONSIBLE_PARTIES>, F<api.yaml> and
L<https://trac.parrot.org/parrot/wiki/Languages>.
+=item 6
+
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.
+=item 7
+
You might also select a name (and optionally a quote) for your release.
For example, you could select a name from
L<http://en.wikipedia.org/wiki/List_of_parrots>.
+=item 8
+
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.
-=item 1.
+=back
+
+=head2 II. Check C<git> Status
The day of the release has come.
Make sure you have the most recent version of the master branch:
@@ -68,49 +102,55 @@ been pushed out and tested thoroughly. You can check for this with
If there is no output from that command, then your local master
and the master on origin are in sync.
-=item 2.
+=head2 III. Update Version
Update files with version-specific information, but before doing this you
should have parrot configured and have run C<make> with the old version:
=over 4
-=item a
+=item 1
=over 4
-=item i
+=item a
Use C<tools/release/update_version.pl> to update the version string in a
-handful of files. If you are running C<update_version.pl> in a directory with
-an existing build, run C<make reconfig> to clear out any generated bytecode
-that was invalidated by the version change. Note that this script takes care
-of modifying generated code, so C<make bootstrap-ops> is no longer necessary
-for the release process.
+several files.
+
+ perl tools/release/update_version.pl 3.7.0
+
+=item b
- perl tools/release/update_version.pl 1.4.1
+B<IMPORTANT:> The version change you just effected by running
+F<tools/release/update_version.pl> effectively invalidates existing generated
+bytecode. Assuming, as is likely, that you ran C<update_version.pl> in a
+directory with an existing build, you must next run C<make reconfig> to clear
+out this now invalid bytecode. (Note that this script takes care of modifying
+generated code, so C<make bootstrap-ops> is no longer necessary for the
+release process.)
-=item ii
+=item c
Also update the version number, date, and your name in the
the file: F<docs/parrothist.pod>.
-=item iii
+=item d
Update this file, that is F<release_manager_guide.pod>,
to remove the pending release you're in the middle of.
=back
-=item b
+=item 2
Update F<ChangeLog>, F<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.
-=item c
+=item 3
Update release-related information in F<tools/release/release.json>. This will
be used later when making release announcements. There are a few essential
@@ -136,20 +176,20 @@ The URL of the FTP directory where the Parrot tarball can be found.
=back
-=item d
+=item 4
Make sure F<RESPONSIBLE_PARTIES> is still accurate.
-=item e
+=item 5
Give yourself credit for the release in F<CREDITS>.
-=item f
+=item 6
Configure parrot and run C<make distro_tests>, and either fix
what those tests complain about, or fix them so they don't complain.
-=item g
+=item 7
If this is a developer release, or there have been no new entries to the
F<PBC_COMPAT> file, skip this step.
@@ -171,7 +211,7 @@ 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.
-=item h
+=item 8
Make sure everything works:
@@ -185,7 +225,7 @@ harnesses are being run.
=back
-=item 3.
+=head2 IV. Commit Changes
When all is well, then commit your changes:
@@ -199,7 +239,7 @@ flag:
git commit -a -m "awesome and informative commit message"
-Be carefult with C<git commit -a>, it could add files that you do not mean to
+Be careful with C<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:
git show
@@ -212,37 +252,43 @@ Update repository on github.
git push origin master
-=item 4.
+=head2 V. Prepare Tarballs
+
+Prepare and test the release tarball. There are two possible approaches:
-Prepare the release tarball.
+=over 4
+
+=item 1 Via C<make release>
+
+=over 4
+
+=item a
+
+Call:
make release VERSION=a.b.c
-where a.b.c is the version number. This will create the tarball named
-F<parrot-a.b.c.tar.gz>. This will automatically avoid including C<DEVELOPING>
-in the release tarball.
+where a.b.c is a version number like C<3.6.0>. This will create the tarball
+named F<parrot-a.b.c.tar.gz>. This will automatically avoid including
+C<DEVELOPING> in the release tarball.
-=item 5.
+=item b
Untar F<parrot-a.b.c.tar.gz> into another area.
-=item 6.
+=item c
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
-Verify that the version is correct and doesn't contain the suffix C<devel>:
-
- ./parrot -V
-
-=over 4
+=back
-=item * C<make release_check>
+=item 2 Via C<make release_check>
-As an alternative to steps 4, 5 and 6 above, you may wish to call:
+As an alternative, 5 and 6 above, you may wish to call:
perl Configure.pl
make release_check
@@ -253,49 +299,57 @@ retest (through C<make test>) and rerelease.
=back
-=item 7.
+Whichever of these two approaches you take, verify that the version is correct
+and does B<not> contain the suffix C<devel>:
+
+ ./parrot -V
+
+=head2 VI. Tag Release
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
-=item 8.
+=head2 VII. FTP Server
-SSH to ftp-osl.osuosl.org. Note that your ssh public key must be added to list
-of authorized keys before you can log in. Contact a previous release manager
-to get your key added.
+Log in to ftp-osl.osuosl.org.
ssh parrot@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
F<~/ftp/releases/devel>.
- mkdir ~/ftp/releases/devel/a.b.c
+ mkdir ~/ftp/releases/devel/a.b.c
If the release is in the supported series (L<Appendix 1 - Upcoming releases>)
create the new directory in F<~/ftp/releases/supported> instead.
- mkdir ~/ftp/releases/supported/a.b.c
+ mkdir ~/ftp/releases/supported/a.b.c
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 \
- parrot@ftp-osl.osuosl.org:~/ftp/releases/devel/a.b.c/.
+ 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/
(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.
- ~/trigger-parrot
+ ~/trigger-parrot
Check your changes at F<ftp://ftp.parrot.org/pub/parrot/releases>. It should
only take a few minutes for the mirrors to sync.
-=item 9.
+=head2 VIII. Release Announcement
Compose the release announcement. Use F<tools/release/crow.pir> to make
this part easier. You can specify the format of your announcements like so:
@@ -311,14 +365,14 @@ 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 C<make release>.
-=item 10.
+=head2 IX. Update Website
Update the website. You will need an account with editor rights
on L<http://www.parrot.org>.
=over 4
-=item a
+=item 1
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
@@ -327,36 +381,36 @@ old announcements as a guide.
The "<!--break-->" line marks the end of the text that will appear on the
front page.
-=item b
+=item 2
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).
-=item c
+=item 3
Under "URL path settings" uncheck "Automatic alias" and set the path to
news/[year]/Parrot-[release number].
-=item d
+=item 4
Under "Publishing options" make sure "Published" and "Promoted to front page"
are checked.
-=item e
+=item 5
Under "Administer" -> "Site building" -> "URL Redirects", change the URL for
"release/current" to the FTP file for the new release (for example,
F<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.
-=item f
+=item 6
-Update docs.parrot.org. Run "make html" in a release copy of parrot, and save
-the resources/ and html/ directories created in docs/. ssh into the parrotvm,
+Update docs.parrot.org. Run C<make html> in a release copy of parrot, and save
+the F<resources/> and F<html/> directories created in F<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 C<latest> symlink to point to your new
@@ -371,48 +425,48 @@ 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.)
-=item 11.
+=head2 X. Publicity
Publicize the release by publishing the announcement through the
following channels (and any others you can think of):
=over 4
-=item a
+=item 1
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 C<lwn> at that domain.
-=item b
+=item 2
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.
-=item c
+=item 3
Modify the topic on #parrot, e.g.:
/topic #parrot Parrot 0.4.8 Released | http://parrot.org/
-=item d
+=item 4
Update the wiki frontpage at L<http://trac.parrot.org/parrot/>.
-=item e
+=item 5
Update the Wikipedia entry at
L<http://en.wikipedia.org/wiki/Parrot_virtual_machine>.
-=item f
+=item 6
Update the C2 wiki entry at L<http://c2.com/cgi/wiki?ParrotCode>.
=back
-=item 12.
+=head2 XI. Review Milestones
Review the milestone for the current release in Trac at
L<https://trac.parrot.org/parrot/roadmap>. Close any completed
@@ -421,7 +475,7 @@ 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.
-=item 13.
+=head2 XII. Changes to Trac
Add the version to Trac so new bug reports can be filed against the release.
L<https://trac.parrot.org/parrot/admin/ticket/versions>.
@@ -430,13 +484,11 @@ Make the latest released version the default version for new reports.
Remove any sufficiently old versions listed there.
-=item 14.
+=head2 XIII. Finish
You're done! Help yourself to a beer, cola, or other celebratory drink.
-=back
-
-=head2 ABOUT THIS DOCUMENT
+=head1 ABOUT THIS DOCUMENT
This document was written after a couple of subtly incorrectly assembled
releases--usually when someone forgot to delete F<DEVELOPING> (which is now

0 comments on commit 0d3a111

Please sign in to comment.
Something went wrong with that request. Please try again.