# Copyright (C) 2007-2008, The Perl Foundation.
# $Id: release_manager_guide.pod 28053 2008-06-03 20:44:52Z coke $

=head1 Release Instructions

To prepare a release:

=over 4

=item 0.

Announce to parrot-porters and #parrot at least a couple days in advance,
asking if there are any showstopping bugs.  It's also good to ask for
updates to F<NEWS>, F<CREDITS>, F<PLATFORMS>, F<RESPONSIBLE_PARTIES>,
etc.  You might also select a name for your release (e.g., perhaps
select a name from L<http://en.wikipedia.org/wiki/List_of_parrots>).

=item 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 L<Appendix 1>.

=item 2.

Update files with version-specific information:

=over 4

=item a

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

Also update the version number, date, and your name in the
the files: F<DEVELOPING> and F<docs/parrothist.pod>.

Update this file to remove the pending release you're in the middle of.

=item b

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

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

=over 4

=item C<release.*>

The date of the next release is in L<Appendix 2>.

=item C<rt.tracking>

Create a new ticket for the next release.  Change the URL fragment here to use
that ticket's number.  Please use the release month in the ticket, and *don't*
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.

=item C<rt.saved_search>

Open the link to the previous value of this field.  Copy the resulting full
URL, then change the ticket number in the C<DependedOnBy> parameter to the
ticket for the next release.  Take the entire resulting URL to
L<http://xrl.us/> and get a short URL.  Add that to this field.

=item C<wiki.bugday>

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

=back

=item d

Make sure F<RESPONSIBLE_PARTIES> is still accurate.

=item e

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 f

Run C<perl tools/dev/pbc_header.pl --upd t/native_pbc/*.pbc>
to update version and fingerprint in the native tests.
You may check with C<perl t/native_pbc/*.t>

=item g

Make sure everything works:

 $ make realclean
 $ perl Configure.pl --test ...
 $ make -s all world fulltest html 2>&1 | tee make_log.txt
 # Note that fulltest runs separate harnesses..

It is not necessary to quiet all the codingstd tests for a release.

=back

=item 3.

 svn commit

Presuming everything goes well later, you'll need the revision number
from this commit, write it down.

=item 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
F<parrot-a.b.c.tar.gz>. This will automatically avoid including C<DEVELOPING>
in the release tarball.

=item 5.

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

=item 6.

Make sure everything works:

 $ perl Configure.pl
 $ make world
 $ make fulltest
 $ make docs
 $ make html

=item 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 L<Appendix 1> below.

=item 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 F<docs/project/pause_guide.pod> for more details.

=item 9.

Compose and send out the announcements -- parrot-porters, perl6-language,
perl6-announce, perl5-porters, use Perl, Perl Monks, etc. Don't forget to
include the next scheduled release date.

Use F<tools/util/crow.pir> to make this part easier. You can specify the
format of your announcments 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.

=over 4

=item a

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

=item b

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

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

=item c

Update the next planned release date on the wiki.

=item d

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

Add a release announcement to news/[year]/Parrot-[release].html.
Update C</index.html> (The old mini-announcement may be commented out).
Update C</.htredirects> to point to the proper CPAN URL.

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

If your name is Allison, Will, or chromatic, you will be able to
commit these changes yourself; be sure to test locally in combust
before pushing the update out.  Otherwise, prepare the changes and
send a patch to one of the anointed.

=back

=item 10.

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.

=item 11.

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

=back

=head2 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
automated!), but at least once where the F<MANIFEST> check failed. The intent
of this file is to document what must be done to release so that such mistakes
don't happen again.

=head1 SEE ALSO

F<README>, F<RESPONSIBLE_PARTIES>.

=head1 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 C<svn copy> so that you
know which changes were made on the branch.

This new C<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
C<parrot-release> working copy via C<svn switch> by switching it back
to the trunk (assuming C<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 C<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.  I<Then> go get
that beer!

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

 - June 17th, 2008      - Nuno Carvalho
 - July 15th, 2008      - Bernhard Schmalhofer
 - August 19th, 2008    - Bob Rogers
 - September 16th, 2008 - Patrick R. Michaud
 - October 21st, 2008   - Jerry Gay
 - November 18th, 2008  - chromatic
 - December 16th, 2008  - Andrew Whitworth

=cut
