path: root/tools/star/release-guide.pod

=head1 Guide to Rakudo Star releases

Rakudo Star releases are based on Rakudo compiler releases.
Since some time is often needed for module updates and testing
after each Rakudo compiler release, the timing of Star releases
varies from one release to the next.

Also, while the Rakudo compiler issues monthly releases, Star
releases are free to choose a longer release cycle.  Star releases
are also free to choose older releases of the compiler, NQP, or
MoarVM.  The goal is to balance end-user stability needs with
progress being made on the compiler, modules, and other runtime
components.  Currently, Star is on a quarterly release cycle.

=head2 Steps to create a release

If this is your first time releasing, B<read the whole guide before
starting>. That way you can ask questions and clear up and confusions before
you're in the thick of it.

If you have done this before, you might want to check for and read any changes
to this release guide since your last run.

Any time this guide tells you to commit changes, you may also push them if you
wish to do so. Step 8 will make sure you do this regardless.

=over 4

=item Step 0

Make sure you have a working C<perl6> binary in your C<$PATH>. Refer to
L<http://rakudo.org/how-to-get-rakudo/> for how to do that. The exact version
isn't very important at the moment, it just shouldn't be a year out of date.

=item Step 1

Clone the git@github.com:rakudo/star repository.

  $ git clone git@github.com:rakudo/star

If you already have a clone of rakudo/star, make sure it is in sync
with github:

  $ git checkout master
  $ git pull origin master
  $ git submodule sync
  $ git submodule update --init --recursive

Verify that

  $ git status

reports a clean repository.

=item Step 2

Change to the star repository directory and edit the first three
lines of F<tools/star/Makefile> to indicate the desired releases of
Rakudo, NQP, and MoarVM to use.

Usually that means the last Rakudo release, the NQP version that is in the
released Rakudo's F<tools/build/NQP_REVISION> file, and the MoarVM version that
is in the F<tools/build/MOAR_REVISION> file that is included in the NQP
release.

  $ cd star
  $ vi tools/star/Makefile

=item Step 3

Run C<make -f tools/star/Makefile> to populate the star directory
with the needed tarballs and module repositories for building Rakudo Star:

  $ make -f tools/star/Makefile

You may at times be prompted for your SSH key/pass combo.

Assuming the Makefile ran successfully, you should now commit your changes.

  $ git commit tools

=item Step 4

If there are any new modules to be added, use C<git submodule> to add
its repo to the modules/ directory.  Also add the module directory
name to the C<modules/MODULES.txt> file.

  $ git submodule add git@github.com:user/acme-example modules/acme-example
  $ echo acme-example >>modules/MODULES.txt
  $ git commit . -m "Added acme-example to installed modules."

=item Step 5

Verify that all of the git submodules are at the desired commit
for the Star release.  To bring all modules up to the current
C<master> branch, one can do:

  # pull master in each submodule dir
  $ git submodule foreach git pull origin master

Create a temporary file as a basis for the module changelog to be
included in release announcement below:

  $ git diff --submodule=log > /tmp/mod.txt

Then you may commit your update of the submodules:

  # commit submodules state to star repo
  $ git commit modules

=item Step 6

If one doesn't already exist, create a release announcement in
C<docs/announce/YYYY.MM.md>.  You can often use the previous release's
file as a starting point, updating the release number, version
information, name, etc., as appropriate.  Be sure to pay attention
to any changes listed in Rakudo's ChangeLog.

  $ vi docs/announce/YYYY.MM.md
  $ git add docs/announce/YYYY.MM.md
  $ git commit docs

The module changelog temporary file above can be used to help with
the corresponding section in the announcement.

At this point it is strongly advised that you push your changes so far, to get
feedback on your announcement while you do other steps.

  $ git push

=item Step 7

Update the release number in the C<README> and C<Makefile.in> files.

  $ vi README tools/build/Makefile.in
  $ git commit README tools/build/Makefile.in

=item Step 8

Make sure any locally modified files have been pushed
back to github.

  $ git status
  $ git push

=item Step 9

Create a candidate release tarball:

  $ make -f tools/star/Makefile release VERSION=2012.08

This will create a tarball C<rakudo-star-2012.08.tar.gz> in the
current directory.

=item Step 10

Unpack the tarball somewhere else, and do a test build/install:

  $ mkdir work
  $ cd work
  $ tar xvfz ../rakudo-star-2012.08.tar.gz
  $ cd rakudo-star-2012.08
  $ perl Configure.pl --gen-moar
  $ make install
  $ make rakudo-test
  $ make rakudo-spectest
  $ make modules-test

If there are failures in any of C<rakudo-test>, C<rakudo-spectest>, or
C<modules-test>, then do your best to fix them and return to step 8.

STOP THE RELEASE PROCESS (i.e., do not issue a release) if there
are any errors that you're unable to fix.  File issue tickets
(https://github.com/rakudo/star/issues) for failing tests
and report them to C<#perl6>.

=item Step 11

Tag the release by its release month ("YYYY.MM").

  $ git tag -s -a -m"tag release YYYY.MM" YYYY.MM    # e.g. 2012.08
  $ git push --tags

The C<-s> tells git to sign the release with your PGP/GPG key, so it will
likely ask you for the passphrase of your secret key.  Note some versions of
git/gpg don't correctly prompt for passphrase or display a meaningful error
when it's absent.

If you have no PGP key, you might need to
L<create one first|https://fedoraproject.org/wiki/Creating_GPG_Keys>. Should
that prove impossible, you can omit the C<-s> from the command line.

Also sign the release tarball with GPG and a suitable key
eg. C<gpg --armor --detach-sig rakudo-star-2018.01.tar.gz>

Generate a SHA256 sum eg.

 $ sha256sum rakudo-star-2018.01.tar.gz | cut -f1 -d" " > rakudo-star-2018.01.tar.gz.sha256.txt

=item Step 12

Upload the release tarball to L<http://rakudo.org/downloads/star> and L<https://rakudo.perl6.org/downloads/star/>:

 $ scp rakudo-star-2012.08.tar.gz rakudo@rakudo.org:public_html/downloads/star

Also upload the detached signature eg. C<rakudo-star-2018.01.tar.gz.asc>
and sha256 sum eg. C<rakudo-star-2018.01.tar.gz.sha256.txt>

If you don't have permission to do this step, please ask one of the core devs
(pmichaud, jnthn, masak, PerlJam/perlpilot, tadzik, or moritz) on C<#perl6> to do
it for you.

=item Step 13

Commit announcement to the rakudo.org repo automatically by running the following
command.  You will need C<perl6> in the C<PATH> and to C<zef install WWW> if you don't
have it.

You can also make and commit the post manually, but if you do, be sure
to add C<%% title:> and C<%% date:> metadate to the top of the file:

  cd $(mktemp -d) &&
  git clone git@github.com:perl6/rakudo.org/. &&
  ./push-latest-rakudo-star-announcement.p6 2018.01

You will also have to bump versions manually in C<templates/files.html.ep> in
the rakudo.org repo.

Publicize the release in the appropriate places.  These include:

=over 4

=item * http://perl6.org/

=item * perl6-users@perl.org

=item * perl6-language@perl.org

=item * perl6-compiler@perl.org

=item * http://en.wikipedia.org/wiki/Rakudo_Perl_6 (latest release date is mentioned in the main text)

=item * http://en.wikipedia.org/wiki/Perl_6

=back

Actively ask others to advertise the release as well. This includes their social
media accounts and blogs. Notable places include:

=over 4

=item * L<http://blogs.perl.org/>

=item * L<Perl 6 Facebook Page|https://www.facebook.com/groups/1595443877388632/>

=item * Reddit: L<r/perl|https://www.reddit.com/r/perl/>, L<r/perl6|https://www.reddit.com/r/perl6/>,
and L<r/programming|https://www.reddit.com/r/programming/>

=item * L<Hacker News|https://news.ycombinator.com/news>

=item * L<Rakudo's Twitter account|https://twitter.com/rakudoperl>

=back

=item Step 14

Add this release and your name to the list of releases at the end of this
document (F<tools/star/release-guide.pod>).

    $ vim tools/star/release-guide.pod
    $ git add tools/star/release-guide.pod
    $ git commit -m 'note YYYY.MM release in release-guide.pod

=item Step 15

You're done!  Celebrate with the appropriate amount of fun.

=back

=head2 Star Releases

    Release         Release Manager
    =======         ===============

    2010.07         pmichaud
    2010.08         pmichaud
    2010.09         pmichaud
    2010.10         pmichaud
    2010.11         pmichaud
    2010.12         pmichaud

    2011.01         pmichaud
    2011.04         pmichaud
    2011.07         pmichaud

    2012.01         jnthn
    2012.02         jnthn
    2012.04         moritz
    2012.05         moritz
    2012.06         moritz
    2012.07         pmichaud
    2012.08         pmichaud
    2012.09         pmichaud
    2012.10         jnthn
    2012.11         moritz
    2012.12         moritz

    2013.01         moritz
    2013.02         moritz
    2013.05         pmichaud
    2013.08         moritz
    2013.09         moritz
    2013.10         lue
    2013.11         moritz
    2013.12         lue

    2014.01         tadzik
    2014.03         FROGGS
    2014.04         jnthn
    2014.08         FROGGS
    2014.09         FROGGS
    2014.12         moritz

    2015.01         moritz
    2015.02         moritz
    2015.03         moritz
    2015.06         FROGGS
    2015.07         moritz
    2015.09         moritz
    2015.11         moritz

    2016.01         FROGGS
    2016.04         stmuk
    2016.07         stmuk
    2016.10         stmuk
    2016.11         stmuk

    2017.01         stmuk
    2017.04         stmuk
    2017.07         stmuk
    2017.10         stmuk

    2018.01         stmuk
    2018.04         stmuk
    2018.06         stmuk
    2018.10         stmuk

    2019.03         hankache, clarkema

=cut