=encoding UTF-8

=head1 release_guide.pod - guide to Rakudo releases

Rakudo’s development release cycle is the third Saturday of
each month.

Each development release is given a sequential number and a name based
on the release year and month.  Older releases had code names based on
an active Perl Mongers group.

For releases made so far, see the list of development releases at the
end of this document.

=head2 Planned future releases

Note that we are trying very hard to ensure there are no backward
compatibility issues post version 6.c. As such, we may end up delaying
some releases to ensure any compatibility issues are resolved.

  2020-12-19   Rakudo #142 (Altai-man + Releasable)

(More planned dates can be generated with F<tools/release-dates.p6>).

=head2 Steps to create a release (for release managers)

B<⚠ Please try to rely on automation instead of doing the release
manually.> This document describes steps that should be performed
by tools, and in a way serves as a documentation for them.

Currently there are two tools:

=over

=item *
L<Release Sakefile|https://github.com/rakudo/rakudo/blob/master/tools/releasable/Sakefile>
which is meant to be used together with
L<Releasable|https://github.com/Raku/whateverable/wiki/Releasable> bot

=item *
L<NeuralAnomaly|https://github.com/zoffixznet/na> bot

=back

Some things are hard to automate, and you have to understand what is
(and what is not) done by the tool you are using, so read on.

=over 4

=item 1.

A few days before the Rakudo release, it’s a good idea to...

=over 4

=item *

Remind people of the upcoming release, invite people to update the
L<ChangeLog|https://github.com/rakudo/rakudo/wiki/ChangeLog-Draft>,
etc. Note that the ChangeLog is kept on the wiki so that people can
easily do minor corrections, but for the release it has to be moved
into C<docs/ChangeLog>.

=item *

Check if any DEPRECATED code needs to be removed because the end of the
deprecation cycle is reached.  One way of doing this, is to grep on the
YYYYMM of the release (e.g. 201412 for the 2014.12 release).  If you find
any occurrences, remove the code and make sure the spectest is still ok.

=item *

Review the issue tracker for tickets that might need resolving
prior to the release, addressing them as needed.  “Tickets
that need resolving” is left to your discretion.  Any problem
that has a large impact on users is worth addressing either
as a fix or as prominent documentation (the README and/or
the release announcement).

=item *

B<Bump often>, especially the day before the release. Otherwise issues
with MoarVM/NQP might go unnoticed for too long.

=item *

Create a draft release announcement in docs/announce/YYYY.MM.md in
markdown format.  You can often use the previous release’s file as a
starting point, updating the release number, version information, name,
etc. as appropriate.

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

There is a helper script C<tools/create-release-announcement.raku> that
will create a basic release announcement for you based on the state
of the repository and the current date.  Feel free to use it to
save yourself some time, but please look over its output if you decide
to use it:

    ./raku tools/create-release-announcement.raku > docs/announce/YYYY.MM.md

=item *

If it’s a month relatively early in the calendar year,
double-check that the copyright date in the README file includes
the current year.  (It’s not necessary to update copyright dates
in other files, unless you know that a given file has been modified
in a year not reflected by the file’s copyright notice.)

=item *

To spot more regressions, it’s a good idea to test the ecosystem and see
if there are any modules that were working correctly (e.g. passing their
tests) on the previous release but no longer work on HEAD. One of the
tools to do that is
L<Blin|https://github.com/Raku/Blin>.

Generally, any kind of breakage in modules is unwanted, but there are
exceptions. Submit Pull Requests to anything that is affected and file
rakudo tickets for all unwanted changes in Rakudo behavior.

=item *

If the release is nearing and you see that the state of Rakudo on HEAD
is inherently unstable (less stable than the previous release, or worse
than the previous release for other reasons), assess your options.
Even though rakudo releases are scheduled for every month, it doesn't
necessarily mean that there I<must> be a release every month. Cancelling
the release is an option. However, see if anything else can be done,
like if offending commits can be reverted, or if you can make a release
from an earlier state (e.g. previous release + some commits +
cherry-picked important fixes).

=back

=item 2.

Update Rakudo’s leap-second tables:

  perl tools/update-tai-utc.pl

If a new leap second has been announced, F<src/core.c/Rakudo/Internals.pm6>
will be modified, so commit the new version. B<Note:> be sure to double
check the modifications are correct before committing.

  git commit src

But probably there won’t be any new leap seconds, in which case the file
will be unchanged.

B<Note>: this program requires the perl modules L<Time::y2038>,
L<LWP::Simple> and L<File::Slurp> to be installed.

=item 3.

As the actual release date nears, review the git log history
to see if any additional items need to be added to the ChangeLog.
This can be conveniently done with

  git log --since=yyyy-mm-dd --reverse # find commits
  # update ChangeLog
  git commit docs/ChangeLog # commit changes

=item 4.

When it’s time to cut the release, finalize the new release
announcement in docs/announce/YYYY.MM.md .  (If one hasn’t already
been created, see step 1 above.) Highlight areas in which the
new release is significant.

Include a list of contributors since the last release in the announcement.
You can get an automatically generated list by running

  ./raku tools/contributors.raku

To obtain all contributors, ensure you have all supporting repositories
checked out, before running (this can be achieved by building rakudo
and running a spectest). Please check the result manually for duplicates
and other errors. Note that you may not be able to run your system raku
in a local checkout, you may have to wait until you build in this
directory and use C<./raku>.

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

=item 5.

Update the release dates and names at the bottom of this file
(F<docs/release_guide.pod>).  Also improve these instructions if
you find any steps that are missing.

  git commit docs/release_guide.pod

=item 6.

Ensure that a monthly MoarVM release has been completed. Those
releases are typically handled by a separate team. Since you are going
to perform smoke testing of the ecosystem, it is likely that MoarVM
release team will wait for your confirmation before cutting a
release. Make sure that MoarVM builds on Windows (see AppVeyor
status). It is also a good idea to look for JVM issues at this point.

=item 7.

Create an NQP release with the same C<YYYY.MM> version number
as Rakudo. Follow NQP’s
L<docs/release_guide.pod|https://github.com/Raku/nqp/blob/master/docs/release_guide.pod>
file to do that.

=item 8.

Go back to the Rakudo repository, and update the NQP dependency:

  echo YYYY.MM > tools/build/NQP_REVISION
  git commit -m '[release] bump NQP revision' tools/build/NQP_REVISION

=item 9.

Enter the new version into the F<VERSION> file, and commit the changes:

  echo YYYY.MM > VERSION
  git commit -m '[release] bump VERSION' VERSION

=item 10.

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

  git status
  git push

=item 11.

Make sure everything compiles and runs from a known clean state:

  make realclean
  perl Configure.pl --gen-moar --backends=ALL
  make
  make install
  make test

=item 12.

Install Inline::Perl5 so stresstest can use it.

  git clone https://github.com/ugexe/zef
  export PATH=`pwd`/install/bin:$PATH
  cd zef; raku -Ilib bin/zef install .
  cd ..
  export PATH=`pwd`/install/share/perl6/site/bin:$PATH
  zef install Inline::Perl5

=item 13.

Now run the stresstests for stable and lastest specs. The following commands
assume you already have a roast checkout in C<t/spec>. If not, run
C<make spectest> (you can abort it  after the repository is retrieved).

  (cd t/spec && git checkout master)     # test latest language spec
  make stresstest
  (cd t/spec && git checkout 6.c-errata) # test stable language spec (6.c)
  make stresstest
  (cd t/spec && git checkout 6.d-errata) # test stable language spec (6.d)
  make stresstest

There are many tests to run for the stresstest target.  If
you have a machine with multiple CPU cores, you may want to
execute that last as

  TEST_JOBS=4 make stresstest

where 4 is the number of CPU cores.  This should make the
total time to execute all of the tests dramatically less.

Note that any failures against the stable language spec B<must> be
fixed before a release can be made. Also, you will see warnings about
missing test files; this is because we only have one list of files,
and new tests may have been added after the last version of the spec
was frozen.

Continue adjusting things until make stresstest passes as expected.
Often this means fixing a bug, fudging a test, or (temporarily?)
commenting out a test file in C<t/spectest.data>.  Use your best
judgment or ask others if uncertain what to do here.

=item 14.

B<Caution>: this step removes any untracked files in F<t/spec>.
So please make a backup if you have any important data in there.

Create a tarball by entering C<make release VERSION=YYYY.MM>,
where YYYY.MM is the month for which the release is being made.
This will create a tarball file named C<rakudo-YYYY.MM.tar.gz>.

Because we tested the stable language spec last, above, those
are the tests that will end up in the release tarball.

=item 15.

Unpack the tar file into another area, and test that it
builds and runs properly using the same process in steps 11-13.
For step 13, just run "make stresstest"; you're only testing
the official spec tests here, and cannot switch between branches.
If there are any problems, fix them and go back to step 11.

=item 16.

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

  git tag -u <email> -s -a -m "tag release #nnn" YYYY.MM    # e.g., 2013.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.

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.

Be sure to upload your public key to your GitHub account, so that GitHub
displays the I<Verified> button next to the tag. You can do that by running
C<< gpg --armor --export <email> >> and adding the output as the
I<New GPG Key> at the bottom of the
L<< settings -> keys page|https://github.com/settings/keys >>

=item 17.

Sign the tarball with your PGP key:

    gpg -b --armor rakudo-YYYY.MM.tar.gz

=item 18.

Upload the tarball and the signature to L<http://rakudo.org/downloads/rakudo>:

  scp rakudo-YYYY.MM.tar.gz rakudo-YYYY.MM.tar.gz.asc \
       rakudo@rakudo.org:public_html/downloads/rakudo/


If you do not have permissions for that, ask one of (jnthn,
masak, tadzik, moritz, [Coke], lizmat, timotimo,
 AlexDaniel) on #raku or #raku-dev to do it for you.

=item 19.

Build binary packages by following the steps in C<docs/release_guide_binary.md>.
for Linux 64bit and Windows 64bit.

=item 20.

To avoid public confusion with Rakudo Star releases, we now publish
compiler release announcements ONLY to perl6-compiler@perl.org.
(We may restart widespread announcements of compiler releases
once they are known, or we may begin publishing a single
announcement for both.)

Don’t send out any announcements until the files are actually available
per step 14 above.

=item 21.

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

=item 22.

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

=back

=head2 Releases so far

Previous releases were bundled as part of monthly Parrot releases.

  2009-02-26   Rakudo #14 "Vienna"             (pmichaud)
  2009-03-20   Rakudo #15 "Oslo"               (pmichaud)
  2009-04-23   Rakudo #16 "Bratislava"         (pmichaud)
  2009-05-21   Rakudo #17 "Stockholm"          (pmichaud)
  2009-06-18   Rakudo #18 "Pittsburgh"         (pmichaud)
  2009-07-23   Rakudo #19 "Chicago"            (moritz)
  2009-08-20   Rakudo #20 "PDX"                (kyle)
  2009-09-17   Rakudo #21 "Seattle"            (particle)
  2009-10-22   Rakudo #22 "Thousand Oaks"      (duff)
  2009-11-19   Rakudo #23 "Lisbon"             (masak)
  2009-12-17   Rakudo #24 "Seoul"              (chromatic)
  2010-01-22   Rakudo #25 "Minneapolis"        (pmichaud)
  2010-02-18   Rakudo #26 "Amsterdam"          (mberends)
  2010-03-18   Rakudo #27 "Copenhagen"         (smash)
  2010-04-22   Rakudo #28 "Moscow"             (moritz)
  2010-05-20   Rakudo #29 "Erlangen"           (colomon)
  2010-06-17   Rakudo #30 "Kiev"               (masak)
  2010-07-22   Rakudo #31 "Atlanta"            (Coke)
  2010-08-19   Rakudo #32 "Pisa"               (mathw)
  2010-09-23   Rakudo #33 "Milan"              (moritz)
  2010-10-21   Rakudo #34 "Paris"              (duff)
  2010-11-18   Rakudo #35 "Melbourne"          (masak)
  2010-12-23   Rakudo #36 "New York"           (smash)
  2011-01-20   Rakudo #37 "BristolBath"        (tadzik)
  2011-02-17   Rakudo #38 "Toulouse"           (arnsholt)
  2011-03-17   Rakudo #39 "Orlando"            (jdhore)
  2011-04-21   Rakudo #40 "ZA"                 (duff)
  2011-05-19   Rakudo #41 "Dahut"              (jdhore)
  2011-06-23   Rakudo #42 "Bruxelles"          (jdhore)
  2011-07-21   Rakudo #43 "Beijing"            (mberends,moritz)
  2011-09-30   Rakudo #44 "Riga"               (tadzik)
  2011-10-20   Rakudo #45 "Houston"            (duff)
  2011-11-17   Rakudo #46 "London"             (tadzik)
  2011-12-22   Rakudo #47 "Columbus"           (moritz)
  2012-01-23   Rakudo #48 "Toronto"            (moritz)
  2012-02-23   Rakudo #49 "SPb"                (masak)
  2012-03-22   Rakudo #50 "Argentina"          (masak)
  2012-04-19   Rakudo #51 "Brazos Valley"      (Coke)
  2012-04-25   2012.04.1                       (moritz)
  2012-05-17   Rakudo #52 "MadMongers"         (tadzik)
  2012-06-21   Rakudo #53 "Strasbourg"         (duff)
  2012-07-19   Rakudo #54 "Tallinn"            (masak)
  2012-08-23   Rakudo #55 "Frankfurt"          (tadzik,moritz)
  2012-09-20   Rakudo #56 "Perl"               (masak)
  2012-09-29   2012.09.1                       (pmichaud)
  2012-10-18   Rakudo #57 "Tokyo"              (duff)
  2012-11-22   Rakudo #58 "Walnut"             (FROGGS)
  2012-12-20   Rakudo #59 "Warszawa"           (masak)
  2013-01-17   Rakudo #60 "Sonoma"             (isBEKaml)
  2013-02-21   Rakudo #61 "drinkers"           (tadzik)
  2013-02-23   2013.02.1                       (moritz)
  2013-03-21   Rakudo #62 "Singapore"          (masak)
  2013-04-18   Rakudo #63 "Albany"             (Coke)
  2013-05-23   Rakudo #64 "Austin"             (FROGGS)
  2013-06-20   Rakudo #65 "Poznan"             (masak)
  2013-07-18   Rakudo #66 "Edinburgh"          (moritz,lizmat)
  2013-08-22   Rakudo #67 "Bicycle"            (moritz)
  2013-09-19   Rakudo #68 "Shanghai"           (masak)
  2013-10-17   Rakudo #69 "Roederbergweg"      (Coke)
  2013-11-21   Rakudo #70 "Malmö"              (lizmat)
  2013-12-19   Rakudo #71 "Advent"             (moritz)
  2014-01-23   Rakudo #72 "Plano"              (masak)
  2014-02-20   Rakudo #73 "Karlsruhe"          (timotimo)
  2014-03-20   Rakudo #74 "Adelaide"           (tadzik)
  2014-04-17   Rakudo #75 "Echt"               (masak)
  2014-05-22   Rakudo #76 "Bajor"              (FROGGS)
  2014-06-19   Rakudo #77 "Gdańsk"             (sergot)
  2014-07-17   Rakudo #78 "Sofia"              (FROGGS)
  2014-08-21   Rakudo #79 "Minsk"              (Coke)
  2014-09-18   Rakudo #80 "HongKong"           (masak)
  2014-10-23   Rakudo #81 "Linz"               (duff)
  2014-11-20   Rakudo #82 "Helsinki"           (lizmat)
  2014-12-18   Rakudo #83 "Cologne"            (lizmat)
  2014-12-19   2014.12.1                       (lizmat)
  2015-01-22   Rakudo #84 "Gotanda"            (Coke)
  2015-02-19   Rakudo #85 "Berlin"             (lizmat)
  2015-03-19   Rakudo #86 "Cluj"               (FROGGS)
  2015-04-23   Rakudo #87 "Vladivostok"        (masak)
  2015-05-21   Rakudo #88 "Dresden"            (FROGGS)
  2015-06-18   Rakudo #89 "Salt Lake"          (hoelzro)
  2015-07-24   Rakudo #90 "Prague"             (masak)
  2015-07-24   2015.07.1                       (masak)
  2015-07-25   2015.07.2                       (moritz)
  2015-09-17   Rakudo #91 "Zürich"             (Coke)
  2015-10-22   Rakudo #92 "Niceville"          (Coke) # v6.b
  2015-11-19   Rakudo #93 "Bend"               (Coke)

  2015-12-25   Rakudo #94 "коледа"             (Coke) # v6.c
  2016-02-01   Rakudo #95 "2016.01"            (Coke)
  2016-02-02   2016.01.1                       (Coke)
  2016-02-21   Rakudo #96 "2016.02"            (Coke)
  2016-03-23   Rakudo #97 "2016.03"            (Coke)
  2016-04-19   Rakudo #98 "2016.04"            (Coke)
  2016-05-21   Rakudo #99 "2016.05"            (hoelzro)
  2016-06-18   Rakudo #100 "2016.06"           (Zoffix)
  2016-07-16   Rakudo #101 "2016.07"           (Zoffix)
  2016-07-18   2016.07.1                       (Zoffix)
  2016-08-20   Rakudo #102 "2016.08"           (Zoffix)
  2016-08-20   2016.08.1                       (Zoffix)
  2016-09-17   Rakudo #103 "2016.09"           (Zoffix + NeuralAnomaly)
  2016-10-15   Rakudo #104 "2016.10"           (Zoffix + NeuralAnomaly)
  2016-11-19   Rakudo #105 "2016.11"           (Zoffix + NeuralAnomaly)
  2016-12-17   Rakudo #106 "2016.12"           (Zoffix + NeuralAnomaly)
  2017-01-20   Rakudo #107 "2017.01"           (Zoffix + NeuralAnomaly)
  2017-02-18   Rakudo #108 "2017.02"           (Zoffix + NeuralAnomaly)
  2017-03-18   Rakudo #109 "2017.03"           (Zoffix + NeuralAnomaly)
  2017-04-17   Rakudo #110 "2017.04"           (Zoffix + NeuralAnomaly)
  2017-04-18   2017.04.1                       (Zoffix)
  2017-04-18   2017.04.2                       (Zoffix)
  2017-04-23   2017.04.3                       (Zoffix)
  2017-05-20   Rakudo #111 "2017.05"           (Zoffix + NeuralAnomaly)
  2017-06-17   Rakudo #112 "2017.06"           (Zoffix + NeuralAnomaly)
  2017-07-15   Rakudo #113 "2017.07"           (Zoffix + NeuralAnomaly)
  2017-08-21   Rakudo #114 "2017.08"           (AlexDaniel + Releasable)
  2017-09-18   Rakudo #115 "2017.09"           (AlexDaniel + Releasable)
  2017-10-26   Rakudo #116 "2017.10"           (AlexDaniel + Releasable)
  2017-11-21   Rakudo #117 "2017.11"           (AlexDaniel + Releasable)
  2017-12-21   Rakudo #118 "2017.12"           (AlexDaniel + Releasable)
  2018-01-25   Rakudo #119 "2018.01"           (AlexDaniel + Releasable)
  2018-02-20   Rakudo #120 "2018.02"           (AlexDaniel + Releasable)
  2018-02-23   2018.02.1                       (AlexDaniel + Releasable)
  2018-03-19   Rakudo #121 "2018.03"           (AlexDaniel + Releasable)
  2018-04-25   Rakudo #122 "2018.04"           (AlexDaniel + Releasable)
  2018-04-30   2018.04.1                       (AlexDaniel + Releasable)
  2018-05-24   Rakudo #123 "2018.05"           (AlexDaniel + Releasable)
  2018-06-22   Rakudo #124 "2018.06"           (AlexDaniel + Releasable)
  2018-09-02   Rakudo #125 "2018.08"           (AlexDaniel + Releasable)
  2018-09-23   Rakudo #126 "2018.09"           (AlexDaniel + Releasable)
  2018-10-28   Rakudo #127 "2018.10"           (AlexDaniel + Releasable)

  2018-11-29   Rakudo #128 "2018.11"           (AlexDaniel + Releasable) # v6.d
  2018-12-21   Rakudo #129 "2018.12"           (AlexDaniel + Releasable)
  2019-03-07   Rakudo #130 "2019.03"           (AlexDaniel + Releasable)
  2019-03-17   2019.03.1                       (AlexDaniel + Releasable)
  2019-07-17   Rakudo #131 "2019.07"           (AlexDaniel + kawaii + Releasable)
  2019-07-28   2019.07.1                       (AlexDaniel + Releasable)
  2019-11-26   Rakudo #132 "2019.11"           (AlexDaniel + Releasable)
  2020-01-27   Rakudo #133 "2020.01"           (Altai-man + Releasable)
  2020-02-23   Rakudo #134 "2020.02"           (Altai-man + Releasable)
  2020-03-01   2020.02.1                       (Altai-man)
  2020-05-04   Rakudo #135 "2020.05"           (Altai-man + Releasable)
  2020-05-10   2020.05.1                       (Altai-man)
  2020-06-21   Rakudo #136 "2020.06"           (Altai-man + Releasable)
  2020-07-20   Rakudo #137 "2020.07"           (Altai-man + Releasable)
  2020-08-22   Rakudo #138 "2020.08"           (Altai-man + Releasable)
  2020-08-23   2020.08.1                       (Altai-man + Releasable)
  2020-08-26   2020.08.2                       (Altai-man + Releasable)
  2020-09-26   Rakudo #139 "2020.09"           (Altai-man + Releasable)
  2020-10-24   Rakudo #140 "2020.10"           (Altai-man + Releasable)
  2020-11-21   Rakudo #141 "2020.11"           (Altai-man + Releasable)

=head1 COPYRIGHT

Copyright © 2009-2020, The Perl Foundation.

=cut

# Local Variables:
# fill-column: 100
# End:
# vim: expandtab shiftwidth=4:
