# Copyright (C) 2007-2013, Parrot Foundation.

=pod

=head1 NAME

docs/project/release_manager_guide.pod - The Release Manager Guide.

=head1 DESCRIPTION

This guide lays out in detail the steps necessary to prepare, assemble
and publish a Parrot release.

=head1 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.

=head2 I. Preparations During the Month Before a Release

=over 4

=item 1

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 C<#parrot> or,
alternatively, email a query to the C<parrot-dev> mailing list.  If there are
goals for the release, please announce them on C<parrot-dev>. As well, please
ensure everyone understands what they've committed to accomplish in time for
the release.

=item 2

Shortly after the release preceding to your release, it is a good idea to start
tracking Parrot news in F<ChangeLog>. A good resource is the individual reports
posted in the weekly IRC meeting on C<#parrotsketch>. You may obtain a complete
log of these meetings at L<http://irclog.perlgeek.de/parrotsketch/>.

=item 3

A couple of weeks in advance of the release, ask people to run C<make fulltest>
and report (and hopefully fix!) any problems they discover. Check-in with
language project leaders (I<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
L<https://github.com/parrot/parrot/issues>.

=item 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 C<scp> equivalents.

=over 4

=item * C<ssh parrot@ftp-osl.osuosl.org>

In order to do this, please ensure your public SSH key(s) have been added to
the FTP server L<ftp-osl.osuosl.org>. You can open a support ticket for this by
sending an email to C<support@osuosl.org> with your public SSH keys as
attachments. Without them, you will not be able to ship the release.

=item * C<ssh E<lt>usernameE<gt>@parrot.org>

Also, set up your account on L<http://parrot.org/>. Any previous release
manager should 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 necessary to
contain documentation for new releases.

=back

=item 5

A couple of days in advance, announce the new release to
C<parrot-dev@lists.parrot.org> and to the IRC channel C<#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
L<http://github.com/parrot/parrot/blob/master/ChangeLog>,
L<http://github.com/parrot/parrot/blob/master/CREDITS>,
L<http://github.com/parrot/parrot/blob/master/PLATFORMS>.
L<http://github.com/parrot/parrot/blob/master/RESPONSIBLE_PARTIES>,
L<http://github.com/parrot/parrot/blob/master/api.yaml>,
and L<https://github.com/parrot/parrot/wiki/Languages>.

=item 6

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 C<#parrot>, announcing the
time you plan to start the release procedure. This will aid the committers.

=item 7

You may 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

B<NOTE:> You must have a recent version of Parrot already built for some of the
subsequent steps.

=back

=head2 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.

=head2 III. Update the Release Version

First, ensure you have configured Parrot (C<perl Configure.pl>) and ran
C<make> and C<make html> with the old version of Parrot. Second, save a copy
of the entire F<docs/> directory to some temporary location; you will need
them later in I<Section X> below. Next, update files with the following
version-specific information.

=over 4

=item 1.

=over 4

=item a.

Use C<tools/release/update_version.pl> to 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 F<tools/release/update_version.pl>
did not invalidate existing generated bytecode. Only if you had to update
F<PBC_COMPAT>.
Assuming you ran it in a directory with an existing build, you must now
run C<make reconfig> to update the version in your config files.

=item b.

Update the version number, the date, and your name in L<http://github.com/parrot/parrot/blob/master/docs/parrothist.pod>.

=item c.

Update this file
(L<http://github.com/parrot/parrot/blob/master/docs/project/release_manager_guide.pod>)
to remove the pending release you're currently building.

=back

=item 2

Run

    perl tools/dev/new_changelog_skeleton.pl

to update F<ChangeLog> with the new version number and a skeleton announcement.

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

=item 3

Update release-related information in F<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:

=over 4

=item C<release.nextdate>

The date of the next release (I<see>
L<Appendix 1|"Appendix 1 - Upcoming Releases">).

=item C<bugday.date>

Enter the date of the Saturday before the next release.

=item C<wiki.bugday>

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

=item C<ftp.path>

The URL of the FTP directory where the Parrot tarball can be found.

=item C<release.type>

Either "devel" for a regular development release, or "supported" for a
long-term-support release.

=back

=item 4

Make sure F<RESPONSIBLE_PARTIES> is still accurate.

=item 5

Give yourself credit for the release in F<CREDITS>.

=item 6

Configure Parrot and run C<make distro_tests>. Then either fix what those
tests complain about or fix the tests so they don't complain.

=item 7

B<NOTE:> You may skip the following step if this is a developer release or
if there have been no new entries to F<PBC_COMPAT>.

If this is a supported release and new entries to F<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 F<PBC_COMPAT> run C<sh tools/dev/mk_native_pbc> to
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 F<PBC_COMPAT> was not updated and you got no updated native_pbc files,
you need to update the native pbc headers with
C<perl tools/dev/pbc_header.pl --update-fingerprint t/native_pbc/*.pbc>,
so that the native_pbc tests will not be TODO'd.

=item 8

Verify that the build process runs smoothly:

    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 C<make fulltest> takes a while and that separate harnesses
are being run.

=back

=head2 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 C<git commit> that you
want all modified and deleted files to be in your next commit via the C<-a>
switch:

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

Be careful with C<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:

    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 the repository on GitHub with,

    git push origin master

=head2 V. Prepare the Release Tarballs

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

=over 4

=item 1. Using C<make release>

=over 4

=item a.

Begin by running:

    make release VERSION=a.b.c

where a.b.c is the version number (I<e.g.,> C<3.8.0>). This will create the
tarball named F<parrot-a.b.c.tar.gz>. The F<DEVELOPING> file is automatically
excluded from the release tarball.

=item b.

Extract F<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

=item 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

=back

=item 2. Using C<make release_check>

As an alternative, you can package the release by running:

    perl Configure.pl
    make release_check

This target (or, for short, C<make relcheck>), will prepare the tarball, copy it
into a temporary directory, and then reconfigure, rebuild, re-test
(with C<make test>) and re-release.

=back

Whichever of these two approaches you use, verify the version is correct and
B<does not> contain the suffix C<devel>:

    ./parrot -V

=head2 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

=head2 VII. Push Tarballs to the FTP Server

Log in to L<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
F<~/ftp/releases/devel>:

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

If this is a supported release, (see
L<Appendix 1|"Appendix 1 - Upcoming Releases>), create the new directory in
F<~/ftp/releases/supported> instead:

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

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 \
        parrot@ftp-osl.osuosl.org:~/ftp/releases/devel/a.b.c/

You don't necessarily have to use C<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 F<ftp://ftp.parrot.org/pub/parrot/releases>. It should
only take a few minutes for the mirrors to sync.

=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,

    ./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 C<make release>.

=head2 IX. Update the Website

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

=over 4

=item 1

Create a new page for the release announcement by navigating to going to
L<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.

=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 3

Under I<URL path settings>, uncheck I<Automatic alias> and set the path to
I<news/[year]/Parrot-[release number]>.

=item 4

Under I<Publishing options>, make sure I<Published> and I<Promoted to front
page> are both checked.

=item 5

Under I<Administer> -> I<Site building> -> I<URL Redirects>, change the URL for
C<release/current> to the FTP file for the new release (e.g.
F<ftp://ftp.parrot.org/pub/parrot/releases/devel/3.8.0/parrot-3.8.0.tar.gz>).
Also update the URL for C<release/developer> or C<release/supported> depending
on which type of release this is.

=item 6

Update L<http://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/>. Use
SSH to login to L<< <username>@parrot.org >> and expand these into a release
directory (e.g. 3.8.0) in the webroot (I<i.e.,>
F</var/www/docs.parrot.org/htdocs/parrot>) for L<http://docs.parrot.org>. In
C<< <webroot>/parrot >>, there are symbolic links for C<latest>, C<supported>,
and C<devel>. Update the C<latest> symlink to point to your new directory. If
this is a supported release, also update the C<supported> symlink. Do not
delete any old copies of the docs and don't update the other symlinks.

=item 7

Preview the new page, and submit it.

=back

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

=head2 X. Update parrot.github.com and the Relevant parrot-docsx Repository

To update both the C<parrot.github.com> and the relevant C<parrot-docsx> repositories,
execute the following command:

    perl tools/release/parrot_github_release.pl --docs=[/path/to/old/docs/]

Please note: To review the available options, use the C<-h | --help> option.
In addition, you may also want to review the pod with,
C<perldoc tools/release/parrot_github_release.pl>.

For more information about the update process, I<see>
L<http://github.com/parrot/parrot/blob/master/docs/project/release_parrot_github_guide.pod>.

=head2 XI. Publicity

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

=over 4

=item 1

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

Also, notify Perl Weekly at perlweekly@perlweekly.com .

=item 2

Submit the announcement story to use Perl, Perl Monks, Slashdot, Newsforge,
etc. Don't forget to set a C<Reply-To:> or C<Followup-To:> header, if your mail
client lets you.

=item 3

If you are an IRC op, modify the topic on C<#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.

=item 4

Update the wiki frontpage at L<https://github.com/parrot/parrot/wiki>

=item 5

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

=item 6

Update the C2 wiki entry at L<http://c2.com/cgi/wiki?ParrotCode>.

=back

=head2 XII. Finish

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

=head1 SEE ALSO

L<http://github.com/parrot/parrot/blob/master/README.pod>,
L<http://github.com/parrot/parrot/blob/master/RESPONSIBLE_PARTIES>.

=head1 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
L<http://github.com/parrot/parrot/blob/master/docs/project/support_policy.pod>.

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

(Note that Util's assignment as release manager is provisional; anyone
who wants to take a turn as RM is free to do so for 5.4, 5.5, 5.6, or
later releases; mentorship will be provided. Util is just making sure
that the next three releases are covered.)

    - Jun 18, 2013 - 5.5.0   - Util
    - Jul 16, 2013 - 5.6.0   - Util
    - Aug 20, 2013 - 5.7.0   - ?
    - Sep 17, 2013 - 5.8.0   - ?
    - Oct 15, 2013 - 5.9.0   - dukeleto
    - Nov 19, 2013 - 5.10.0  - ?
    - Dec 17, 2013 - 5.11.0  - ?
    - Jan 21, 2014 - 6.0.0   - dukeleto

=cut

__END__
Local Variables:
  fill-column:78
End:
