# Copyright (C) 2007, The Perl Foundation.
# $Id: release_manager_guide.pod 23821 2007-12-12 21:27:55Z 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 before
releasing, rather than after. Then you could fold the release-oriented
changes into the trunk once the release is done.

TODO: explain how to do this

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

=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 interesting
fields:

=over 4

=item C<rt.tracking>

Create a new ticket for the next release.  Change the URL fragment here to use
that ticket's number.

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

=back

=item d

Make sure F<RESPONSIBLE_PARTIES> is still accurate.

=item e

Configure parrot and run C<perl t/harness t/distro/*.t>, 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.

=item g

Make sure everything works:

 $ make realclean
 $ perl Configure.pl --test ...
 $ make -s all world fulltest html
 # 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-maintainter 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,
PerlMonks, 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, 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. 

Test locally in combust before pushing update out.

=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

parrot repository layout as of end of Apr 2005

 $ svn ls $SVNPARROT
 branches/
 tags/
 trunk/

 $ svn ls $SVNPARROT/tags
 PRE_REL_0_0_8/
 RELEASE_0_0_10/
 RELEASE_0_0_11/
 RELEASE_0_0_13/
 RELEASE_0_0_6/
 RELEASE_0_0_8/
 RELEASE_0_0_9/
 RELEASE_0_1_0/
 RELEASE_0_1_1/
 RELEASE_0_1_2/
 REL_0_0_5/
 V1/
 file_move_031023/
 help/
 ponie-PRE-P5_592/

=head1 Appendix 2

Planned releases in 2008.

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 that will be in
that release.

 - Jan 15th (0.5.2) Bob Rogers
 - Feb 19th (?)     Patrick Michaud
 - Mar 18th (?)     Bernhard Schmalhofer
 - Apr 15th (?)     Jerry Gay
 - May 20th (?)     chromatic
 - Jun 17th (?)     Will Coleda

=cut