release_guide.pod 16 KB
Newer Older
1 2
=encoding UTF-8

3 4
=head1 release_guide.pod - guide to Rakudo releases

5 6 7 8
B<< NOTE: this guide is for a manual release process. You may want
to use the automated process described in
L<docs/release_guide_automated.md|https://github.com/rakudo/rakudo/blob/nom/docs/release_guide_automated.md> >>

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

12 13 14
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.
15

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

19
=head2 Planned future releases
20

21
Note that we are trying very hard to ensure there are no backward
22
compatibility issues post Christmas. As such, we may end up delaying
23
some releases to ensure any compatibility issues are resolved.
24

25
  2017-03-18   Rakudo #109 (Zoffix)
26 27 28 29 30 31 32 33 34
  2017-04-15   Rakudo #110
  2017-05-20   Rakudo #111
  2017-06-17   Rakudo #112
  2017-07-15   Rakudo #113
  2017-08-19   Rakudo #114
  2017-09-16   Rakudo #115
  2017-10-21   Rakudo #116
  2017-11-18   Rakudo #117
  2017-12-16   Rakudo #118
35

36
(More planned dates can be generated with F<tools/release-dates.pl>).
37 38 39 40 41 42 43

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

=over 4

=item 1.

44
A few days before the Rakudo release, it’s a good idea to...
45 46 47 48 49 50

=over 4

=item *

Remind people of the upcoming release, invite people to
51
update the ChangeLog file, update the ROADMAP, etc.
52 53 54

=item *

55 56 57 58 59 60 61
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 *

62
Review the RT queue for tickets that might need resolving
63
prior to the release, addressing them as needed.  “Tickets
64
that need resolving” is left to your discretion.  Any problem
65 66 67 68
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).

69
=item *
70

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

76 77
  git add docs/announce/YYYY.MM.md
  git commit docs
78

79 80 81 82
There is a helper script C<tools/create-release-announcement.pl> 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
83 84 85
to use it:

    ./perl6 tools/create-release-announcement.pl > docs/announce/YYYY.MM.md
86

87
=item *
88

89 90 91
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
92
in other files, unless you know that a given file has been modified
93
in a year not reflected by the file’s copyright notice.)
94

95
=back
96

97
=item 2.
98

99
Update Rakudo’s leap-second tables:
100

101
  perl tools/update-tai-utc.pl
102

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

107
  git commit src
108

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

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

115
=item 3.
116 117 118

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

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

125
=item 4.
126

127 128 129
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
130
new release is significant.
131

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

135
  ./perl6 tools/contributors.pl6
136

137
To obtain all contributors, ensure you have all supporting repositories
138
checked out, before running (this can be achieved by building rakudo
139 140 141 142
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 perl6
in a local checkout, you may have to wait until you build in this
directory and use C<./perl6>.
143

144 145
  git add docs/announce/YYYY.MM.md
  git commit docs
146

147
=item 5.
148

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

153
  git commit docs/release_guide.pod
154

155
=item 6.
156

157 158 159 160 161
Ensure that a monthly MoarVM release has been completed. Those
releases are typically handled by a separate team.

=item 7.

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

167
=item 8.
168

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

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

174
=item 9.
175 176 177

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

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

181
=item 10.
182 183 184

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

185 186
  git status
  git push
187

188
=item 11.
189

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

192 193 194 195 196
  make realclean
  perl Configure.pl --gen-moar --backends=ALL
  make
  make install
  make test
197

198
=item 12.
199 200 201

Install Inline::Perl5 so stresstest can use it.

202
  git clone https://github.com/ugexe/zef
203
  export PATH=`pwd`/install/bin:$PATH
204
  cd zef; perl6 -Ilib bin/zef install .
205 206
  cd ..
  export PATH=`pwd`/install/share/perl6/site/bin:$PATH
207
  zef install Inline::Perl5
208

209
=item 13.
210

211 212 213
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).
214

215 216 217 218
  (cd t/spec && git checkout master)     # test latest language spec
  make stresstest
  (cd t/spec && git checkout 6.c-errata) # test stable language spec
  make stresstest
219 220 221 222 223

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

224
  TEST_JOBS=4 make stresstest
225 226 227

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

229 230 231 232 233
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.
234

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

240
=item 14.
241

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

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

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

252
=item 15.
253 254

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

260
=item 16.
261

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

264 265
  git tag -u <email> -s -a -m "tag release #nnn" YYYY.MM    # e.g., 2013.08
  git push --tags
266

267
The C<-s> tells git to sign the release with your PGP/GPG key, so it will
268
likely ask you for the passphrase of your secret key.
269 270 271 272 273

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.

274 275 276 277 278 279
Be sure to upload your public key to your GitHub account, so that GitHub
displays 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 >>

280
=item 17.
281

282 283
Sign the tarball with your PGP key:

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

286
=item 18.
287

288 289
Upload the tarball and the signature to L<http://rakudo.org/downloads/rakudo>
and L<https://rakudo.perl6.org/downloads/rakudo/>:
290

291
  scp rakudo-YYYY.MM.tar.gz rakudo-YYYY.MM.tar.gz.asc \
292
       rakudo@rakudo.org:public_html/downloads/rakudo/
293 294
  scp rakudo-YYYY.MM.tar.gz rakudo-YYYY.MM.tar.gz.asc \
       rakudo@www.p6c.org:public_html/downloads/rakudo/
295

296
If you do not have permissions for that, ask one of (pmichaud, jnthn, FROGGS,
297 298
masak, tadzik, moritz, PerlJam/perlpilot, [Coke], lizmat, timotimo, fsergot,
hoelzro, Zoffix) on #perl6 or #perl6-dev to do it for you.
299

300
=item 19.
301

302 303 304
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
305 306
once they are known, or we may begin publishing a single
announcement for both.)
307

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

311
=item 20.
312 313 314

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

315
=item 21.
316

317
You’re done!  Celebrate with the appropriate amount of fun.
318 319 320

=back

321 322
=head2 Development releases so far

323 324
Previous releases were bundled as part of monthly Parrot releases.

325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383
  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)
384
  2013-11-21   Rakudo #70 "Malmö"              (lizmat)
385
  2013-12-19   Rakudo #71 "Advent"             (moritz)
386
  2014-01-23   Rakudo #72 "Plano"              (masak)
387 388
  2014-02-20   Rakudo #73 "Karlsruhe"          (timotimo)
  2014-03-20   Rakudo #74 "Adelaide"           (tadzik)
389 390 391 392
  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)
393 394 395 396 397 398 399 400 401
  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)
402 403 404 405 406 407 408
  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)
409 410
  2015-10-22   Rakudo #92 "Niceville"          (Coke) # v6.b
  2015-11-19   Rakudo #93 "Bend"               (Coke)
411

412
  2015-12-25   Rakudo #94 "коледа"             (Coke) # v6.c
413 414 415
  2016-02-01   Rakudo #95 "2016.01"            (Coke)
  2016-02-02   2016.01.1                       (Coke)
  2016-02-21   Rakudo #96 "2016.02"            (Coke)
416
  2016-03-23   Rakudo #97 "2016.03"            (Coke)
417 418
  2016-04-19   Rakudo #98 "2016.04"            (Coke)
  2016-05-21   Rakudo #99 "2016.05"            (hoelzro)
419
  2016-06-18   Rakudo #100 "2016.06"           (Zoffix)
420 421
  2016-07-16   Rakudo #101 "2016.07"           (Zoffix)
  2016-07-18   2016.07.1                       (Zoffix)
422
  2016-08-20   Rakudo #102 "2016.08"           (Zoffix)
423
  2016-08-20   2016.08.1                       (Zoffix)
424
  2016-09-17   Rakudo #103 "2016.09"           (Zoffix + NeuralAnomaly)
425
  2016-10-15   Rakudo #104 "2016.10"           (Zoffix + NeuralAnomaly)
426
  2016-11-19   Rakudo #105 "2016.11"           (Zoffix + NeuralAnomaly)
427 428
  2016-12-17   Rakudo #106 "2016.12"           (Zoffix + NeuralAnomaly)
  2017-01-20   Rakudo #107 "2017.01"           (Zoffix + NeuralAnomaly)
429
  2017-02-18   Rakudo #108 "2017.02"           (Zoffix + NeuralAnomaly)
430

431 432
=head1 COPYRIGHT

433
Copyright (C) 2009-2017, The Perl Foundation.
434 435 436 437 438 439 440

=cut

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