=head1 release_guide.pod - 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. 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 0. Make sure you have a working C binary in your C<$PATH>. Refer to L 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 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 2. Change to the star repository directory and edit the first three lines of F 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 file, and the MoarVM version that is in the F file that is included in the NQP release. $ cd star $ vi tools/star/Makefile =item 3. Run "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 4. If there are any new modules to be added, use "git submodule" to add its repo to the modules/ directory. Also add the module directory name to the 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 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 '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 6. If one doesn't already exist, create a release announcement in 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 7. Update the release number in the README and Makefile.in files. $ vi README tools/build/Makefile.in $ git commit README tools/build/Makefile.in =item 8. Make sure any locally modified files have been pushed back to github. $ git status $ git push =item 9. Create a candidate release tarball: $ make -f tools/star/Makefile release VERSION=2012.08 This will create a tarball rakudo-star-2012.08.tar.gz in the current directory. =item 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 rakudo-test, rakudo-spectest, or 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 #perl6. =item 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. 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. 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 12. Upload the release tarball to L and L: $ scp rakudo-star-2012.08.tar.gz rakudo@rakudo.org:public_html/downloads/star Also upload the detached signature eg. rakudo-star-2018.01.tar.gz.asc and sha256 sum eg. 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 #perl6 to do it for you. =item 13. Commit announcement to the rakudo.org repo automatically by running the following command. You will need perl6 in the PATH and to "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 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 =item * L =item * Reddit: L, L, and L =item * L =item * L =back =item 14 Add this release and your name to the list of releases at the end of this document (F). $ 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 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 =cut