From e0416bf1a9bf810e2ca1591b88c9fc4508fd33c5 Mon Sep 17 00:00:00 2001 From: Patrick Spek Date: Fri, 1 Nov 2019 11:48:30 +0100 Subject: Update release documentation --- README.md | 36 +-- bin/mkchecksum.sh | 24 ++ bin/mkrelease.sh | 2 +- docs/guides/adding-new-community-modules.md | 9 + docs/guides/mac-dmg.pod | 142 +++++++++++ docs/guides/release-guide.pod | 273 ++++++++++++++++++++++ docs/guides/windows-msi.pod | 155 ++++++++++++ tools/star/mac-dmg.pod | 142 ----------- tools/star/release-guide.pod | 350 ---------------------------- tools/star/windows-msi.pod | 155 ------------ 10 files changed, 624 insertions(+), 664 deletions(-) create mode 100644 bin/mkchecksum.sh create mode 100644 docs/guides/adding-new-community-modules.md create mode 100644 docs/guides/mac-dmg.pod create mode 100644 docs/guides/release-guide.pod create mode 100644 docs/guides/windows-msi.pod delete mode 100644 tools/star/mac-dmg.pod delete mode 100644 tools/star/release-guide.pod delete mode 100644 tools/star/windows-msi.pod diff --git a/README.md b/README.md index 5b10faa..14d50a8 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,29 @@ # Rakudo Star -This git repository contains _only_ the tools needed to create a Rakudo Star distribution. +Rakudo Star is a user-oriented distribution of the Raku programming language, +and a number of common community modules. -The `tar` files available from `github.com` -are NOT suitable for building Rakudo Star; do not use them. +This git repository contains _only_ the tools needed to create a Rakudo Star +distribution, not the sources of individual components of the distribution. +These are fetched when you build the distribution tarball. -## Get Rakudo Star -To get the latest release of Rakudo Star, please download the corresponding file depending on your platform. +The `tar` files available from `github.com` for MoarVM, NQP and Rakudo are NOT +suitable for building Rakudo Star; do not use them. Instead, use the tarballs +found on the individual projects' sites, which correctly contain all the +utilities and dependencies used by them. -* [Linux](https://rakudo.org/latest/star/source) -* [Windows](https://rakudo.org/latest/star/win64) -* [macOS](https://rakudo.org/latest/star/macos) +## Get Rakudo Star -## Build Rakudo Star -If you're a Rakudo Star release manager, or someone who wants to create a new Perl 6 -distribution based on the tools here, then run `make -f tools/star/Makefile` to -populate a distribution image. +To get the latest release of Rakudo Star, please download the corresponding +file depending on your platform. -## Guides -* [Release guide](tools/star/release-guide.pod) +- [Linux](https://rakudo.org/latest/star/source) +- [Windows](https://rakudo.org/latest/star/win64) +- [macOS](https://rakudo.org/latest/star/macos) -* [Guide to build MSI packages](tools/star/windows-msi.pod) +## Build Rakudo Star -* [Guide to build DMG packages](tools/star/mac-dmg.pod) +If you're a Rakudo Star release manager, or someone who wants to create a +user-friendly Raku distribution based on the tools here, check the `guides` +directory. This contains documentation on how to make a Rakudo Star tarball, as +well as information on how to create Windows `.msi` and MacOS `.dmg` packages. diff --git a/bin/mkchecksum.sh b/bin/mkchecksum.sh new file mode 100644 index 0000000..735570c --- /dev/null +++ b/bin/mkchecksum.sh @@ -0,0 +1,24 @@ +#! /usr/bin/env sh + +main() +{ + if [ -z "$1" ] + then + usage + exit 1 + fi + + printf "md5 %s\n" "$(md5sum "$1" | cut -f1 -d" ")" + printf "sha1 %s\n" "$(sha1sum "$1" | cut -f1 -d" ")" + printf "sha224 %s\n" "$(sha224sum "$1" | cut -f1 -d" ")" + printf "sha256 %s\n" "$(sha256sum "$1" | cut -f1 -d" ")" + printf "sha384 %s\n" "$(sha384sum "$1" | cut -f1 -d" ")" + printf "sha512 %s\n" "$(sha512sum "$1" | cut -f1 -d" ")" +} + +usage() +{ + printf "NYI\n" +} + +main "$@" diff --git a/bin/mkrelease.sh b/bin/mkrelease.sh index 7c712e0..67df86d 100755 --- a/bin/mkrelease.sh +++ b/bin/mkrelease.sh @@ -17,7 +17,7 @@ main() usage() { - print "NYI" + print "NYI\n" } main "$@" diff --git a/docs/guides/adding-new-community-modules.md b/docs/guides/adding-new-community-modules.md new file mode 100644 index 0000000..42c429f --- /dev/null +++ b/docs/guides/adding-new-community-modules.md @@ -0,0 +1,9 @@ + + +If there are any new modules to be added, use C to add +its repo to the modules/ directory. Also add the module directory +name to the C 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." diff --git a/docs/guides/mac-dmg.pod b/docs/guides/mac-dmg.pod new file mode 100644 index 0000000..7ebc64a --- /dev/null +++ b/docs/guides/mac-dmg.pod @@ -0,0 +1,142 @@ +=head1 Guide to building DMG packages + +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. The dmg packages are based +on these Star releases. + +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, and/or +MoarVM. The goal is to balance end-user stability needs with +progress being made on the compiler, modules, and other runtime +components. + +=head2 Steps to create an DMG package + +A C<.dmg> is a file extension used for an Apple Disk Image which is the most +popular way of running an installer on the Mac desktop + +If this is your first time releasing, B. That way you can ask questions and clear up any 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. + +=over 4 + +=item Step 0 + +Download and install C from Apple if you don't already have the C C +compiler installed. This process was tested on OS X 10.11.x as a build system +using clang-700.1.76 and the result is known to run on as least far back as OS +X 10.9 (and probably further). + +=item Step 1 + +Use your browser to download the latest star release, replace YYYY.MM by year and month: +https://rakudo.perl6.org/downloads/star/rakudo-star-YYYY.MM.tar.gz + +Unpack this C<.tar.gz> to your hard disk. You will get a folder C, again +YYYY.MM is year and month of the star release. + +=item Step 2 + +Change the path to the directory created in the previous step, and run: + + cd ports/darwin_dmg + perl package_darwin_dmg.pl --build -v YYYY MM + +This should automatically compile the MoarVM version of star and all modules and create the C<.dmg> + +In theory this all that needs doing and you can jump to step 4 below. + +=item Step 3 + +Watch the scrollback for errors. + +If the build is interrupted you will have to manually C in the top +level directory before rerunning the previous step. + +Note the C<--build> option will automatically delete the binary destination +directory of C if it exists before running but leaves it in +place after finishing. + +Omitting the C<--build> option will just rebuild the C<.dmg> from C which is useful when debugging the final stage of C<.dmg> build since it's much faster. + +=item Step 4 + +A correct build will create C + +To sanity test + + open Temp_build/Rakudo-Star-YYYY-MM.dmg + +This should automount C and open a Finder window with a +background image of Camelia and "Drag the Rakudo Folder to Applications" +containing a README.txt, a Rakudo folder, Docs folder and a folder representing +a sym link to Applications. + +Delete the directory used to create the C<.dmg>. + + rm -rf /Applications/Rakudo + +Now dragging the C folder to the Applications Link folder (with arrow) +should repopulate C. + +Append your C as suggested in the C and look for reasonable output +from the following kind of commands. + + perl6 -e "say 'hello'" + zef list --installed + p6doc -l + +=item Step 5 + +Stop the release process if you see serious issues with no obvious fix and post +them to the IRC channel or mailing list. If you alter scripts recommit them. + +=item Step 6 + +Generate a SHA256 sum: + + sha256sum rakudo-star-YYYY.MM.dmg | cut -f1 -d" " > rakudo-star-YYYY.MM.dmg.sha256.txt + +=item Step 7 + +Generate a GPG signature for the DMG file: + + gpg --armor --detach-sig rakudo-star-YYYY.MM.dmg + +This will create C. + +=item Step 8 + +Upload the dmg and SHA256 to L: + + rsync -avz rakudo-star-YYYY.MM.dmg* rakudo@www.p6c.org:public_html/downloads/star + +If you don't have permission to do this step, please ask one(pmichaud, jnthn, +masak, PerlJam/perlpilot, tadzik, moritz) on C<#perl6> to do it for you. + +=item Step 9 + +Publicize the dmg packages in the appropriate places. These include: + +=over 4 + +=item * rakudo.org + +=item * #perl6 + +=back + +=item Step 10 + +You're done! Celebrate with the appropriate amount of fun. + +=back + +=cut diff --git a/docs/guides/release-guide.pod b/docs/guides/release-guide.pod new file mode 100644 index 0000000..5bd8ce2 --- /dev/null +++ b/docs/guides/release-guide.pod @@ -0,0 +1,273 @@ +# Rakudo Star release guide + +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. + +## Creating a release distribution + +If this is your first time releasing, **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. + +### Clone this repository + + git clone git://gitlab.com/tyil/rakudo-star.git + +If this is not your first time, you probably already have a copy of this +repository, in which case you should pull the latest changes. + + git pull origin master + +### Branch out + +Since all the information is stored in git, this is a great moment to create a +new branch. This will make it easier to roll back if things go horribly wrong, +and to create a merge request later on to get other people to review the +changes. + + git switch -c $VERSION-rc1 + +### Update all community modules + +All community modules that are going to be bundled with this release need to be +made up-to-date. These are managed as submodules, so `git submodule` comes in +handy here. + + git submodule sync + git submodule update --init --recursive + git submodule foreach git pull origin master + git commit -m "Update submodules" + +At this point `git status` should report a clean repository. + +### Set component versions + +Inside the repository is a Makefile which indicates which versions of upstream +components should be used. This file can be found at `tools/star/Makefile`. +These version numbers are *usually* similar, but not necesarily. Specifically, +it is about the values for `RAKUDO_VER`, `NQP_VER`, `MOAR_VER`. + +If unsure, ask for the specific value for `RAKUDO_VER` in `#raku-dev` on +`irc.freenode.net`. The `NQP_VER` can be found inside the Rakudo repository, in +`tools/build/NQP_REVISION`, and the `MOAR_VER` can be found in the NQP +repository in the `tools/build/MOAR_REVISION` file. + + $EDITOR tools/star/Makefile + git commit -m "Bump component versions" + +### Create a release announcement + +For every release, an announcement should be made. These can be found in +`docs/announce`. They follow the same versioning scheme as Rakudo Star itself, +and as such, the name for the new one should have the current version number, +followed by `.md` since the announcements are in Markdown. + +You should include the latest version number changes, community module changes +(updated ones, deleted ones, new ones), and any other information which might +be relevant to end-users or package maintainers. + + $EDITOR docs/announce/$VERSION.md + git add !$ + git commit -m "Add release announcement for $VERSION" + +### Bump Rakudo Star version number + +The version number for Rakudo Star itself is referred to in another file, +`Makefile.in`, which needs updating. + + $EDITOR tools/build/Makefile.in. + git commit -m "Bump Rakudo Star version" + +### Publish changes + +With all the prep-work done, it is time to build an actual release +distribution. This is done using GitLab CI, so all you need to do now is push +the changes back to the repository. Generally, this would be done through a +merge request, so the changes can be reviewed and approved. Luckily, you're +already using a seperate branch, so this is pretty straightforward as well. + + git push origin $VERSION-rc1 + +This should give you an URL to create a merge request directly, however, if it +does not, you'll have to use your `$BROWSER` to go to the repository web page, +and make one manually. + +### Creating the release candidate + +GitLab CI has been set up to create a new release on every branch or tag. As +such, the previous `git push` should have started a CI job to build a +distribution tarball. If it did not, please consult `#raku-dev` on +`irc.freenode.net`. + +The CI setup also contains a testing phase, where the resulting tarball is +compiled and tested. If any of these steps fail, a solution must be found. The +best place to discuss options would be, again, the `#raku-dev` channel. + +### Creating the official release + +Once the release candidate has been approved to become an official release, the +branch can be merged into `master`. Afterwards, create a new tag for the new +release, and push it to the remote repository. GitLab CI will make a tarball +for you. + + git switch master + git pull origin master + git tag -s $VERSION + git push origin $VERSION + +The `-s` option for `git tag` makes you sign this particular tag with your PGP +key. All tags must be signed, so if you lack a PGP key, you should [strongly +consider to get yourself one](https://fedoraproject.org/wiki/Creating_GPG_Keys). + +### Publishing the official release + +Once GitLab CI has built and tested the final image, you can download it as an +artifact from the job. The job is of stage "Package, and name "Tarball". +Downloading the artifacts will get you a zip file with the tarball inside of +it. Extract the zipfile to some temporary location. Next, create a PGP +signature and checksums for it, to allow other people to verify they got the +right thing. + +For checksumming, a small utility can be found in the `bin` directory, +`mkchecksum`, which will generate a number or checksum formats for a given +file. + + cd -- "$(mktemp -d)" + wget "$ARTIFACTS_URL" + unzip download + cd work/release + gpg --armor --detach-sig *.tar.gz + mkchecksum *.tar.gz > rakudo-star-$VERSION.tar.gz.checksum.txt + +Lastly, the three files you have right now should be uploaded to the remote +server hosting official releases. + +TODO: I currently don't have any information on this step yet! + + 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. + +### Announce the new release + +Now that a new release has been made, you're *technically* done. However, it +would be much appreciated if you also announce to the rest of the world that a +new release has been published. The most important place would be `rakudo.org`. + +#### rakudo.org +The sources of this site can be found in the +[`perl6/rakudo.org`](https://github.com/perl6/rakudo.org repository on GitHub). +It contains a small script to make this easier, called +`push-latest-rakudo-star-announcement.p6`. You will need to have a working +`perl6` in your `$PATH`, and have the `WWW` module installed. + + cd -- "$(mktemp -d)" + git clone git@github.com:perl6/rakudo.org . + ./push-latest-rakudo-star-announcement.p6 $VERSION + +You will also have to bump versions manually in C in +the rakudo.org repo. + +#### Other places of importance + +There are more places around the 'net that should be informed of the new +release. These are not all documented, so you may have to ask around to get +access. + +- http://perl6.org/ +- perl6-users@perl.org +- perl6-language@perl.org +- perl6-compiler@perl.org +- http://en.wikipedia.org/wiki/Rakudo_Perl_6 (latest release date is mentioned in the main text) +- http://en.wikipedia.org/wiki/Perl_6 + +You should actively ask others to advertise the release as well. This includes +their social media accounts and blogs. Notable places include: + +- http://blogs.perl.org/ +- [Perl 6 Facebook Page](https://www.facebook.com/groups/1595443877388632/) +- Reddit: [r/perl](https://www.reddit.com/r/perl/), + [r/rakulang](https://www.reddit.com/r/rakulang/), + [r/programming](https://www.reddit.com/r/programming/) +- [Hacker News](https://news.ycombinator.com/news) +- Twitter: [@rakudoperl](https://twitter.com/rakudoperl) + +### Give yourself some credit + +Add this release and your name to the list of releases at the end of this +document, to eternalize your fame. This may also help other people interested +in making releases to find people to help them when any issues arrive. + + $EDITOR docs/guides/release-guide.md + +You may want to commit and push this file as well, of course. + +**You're done!** Celebrate with the appropriate amount of fun. + +## Rakudo Star release list + +- `2019.03`: hankache, clarkema +- `2018.10`: stmuk +- `2018.06`: stmuk +- `2018.04`: stmuk +- `2018.01`: stmuk +- `2017.10`: stmuk +- `2017.07`: stmuk +- `2017.04`: stmuk +- `2017.01`: stmuk +- `2016.11`: stmuk +- `2016.10`: stmuk +- `2016.07`: stmuk +- `2016.04`: stmuk +- `2016.01`: FROGGS +- `2015.11`: moritz +- `2015.09`: moritz +- `2015.07`: moritz +- `2015.06`: FROGGS +- `2015.03`: moritz +- `2015.02`: moritz +- `2015.01`: moritz +- `2014.12`: moritz +- `2014.09`: FROGGS +- `2014.08`: FROGGS +- `2014.04`: jnthn +- `2014.03`: FROGGS +- `2014.01`: tadzik +- `2013.12`: lue +- `2013.11`: moritz +- `2013.10`: lue +- `2013.09`: moritz +- `2013.08`: moritz +- `2013.05`: pmichaud +- `2013.02`: moritz +- `2013.01`: moritz +- `2012.12`: moritz +- `2012.11`: moritz +- `2012.10`: jnthn +- `2012.09`: pmichaud +- `2012.08`: pmichaud +- `2012.07`: pmichaud +- `2012.06`: moritz +- `2012.05`: moritz +- `2012.04`: moritz +- `2012.02`: jnthn +- `2012.01`: jnthn +- `2011.07`: pmichaud +- `2011.04`: pmichaud +- `2011.01`: pmichaud +- `2010.12`: pmichaud +- `2010.11`: pmichaud +- `2010.10`: pmichaud +- `2010.09`: pmichaud +- `2010.08`: pmichaud +- `2010.07`: pmichaud diff --git a/docs/guides/windows-msi.pod b/docs/guides/windows-msi.pod new file mode 100644 index 0000000..8674c22 --- /dev/null +++ b/docs/guides/windows-msi.pod @@ -0,0 +1,155 @@ +=head1 Guide to build MSI packages + +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. The MSI packages are based +on these Star releases. + +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, and/or +MoarVM. The goal is to balance end-user stability needs with +progress being made on the compiler, modules, and other runtime +components. + +=head2 Steps to create an MSI package + +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. + +=over 4 + +=item Step 0 + +Download and install WiX Toolset, if needed adjust the PATH environment +variable to point to its bin directory. The tools C, C and C +should be available now. + +Install ActivePerl and make sure it is in C. C should give a +sensible output. + +If you do not have the C compiler C installed yet, install the Microsoft +Visual C++ Express for version 2010 or perhaps newer. + +Finally, install the Windows Software Development Kit (SDK) for your Windows +version. + +An alternative to ActivePerl and the Microsoft toolchain is to use Strawberry +Perl which ships with GCC and a mingw toolchain. Run these tools under C +and replace all following references to C by C. + +=item Step 1 + +Make sure there is no C directory, as this will be our installation +target. If there is one, remove it, perhaps after creating backup. + +=item Step 2 + +Use your browser to download the latest star release, replace YYYY.MM by year +and month: https://rakudo.perl6.org/downloads/star/rakudo-star-YYYY.MM.tar.gz + +Unpack this C<.tar.gz> to your hard disk. You will get a folder +C, again YYYY.MM is year and month of the star release. + +=item Step 3 + +Run the Command Line for Visual Studio from the start menu. Alternatively you +can run C followed by C. + +In either case, this should return a valid path: + + echo %VSINSTALLDIR% + +=item Step 4 + +Change the path to the directory created in step 2, and run: + + perl Configure.pl --prefix=C:\rakudo --gen-moar + +This will create a Makefile and will start to compile the MoarVM backend. + +=item Step 5 + +Compile NQP and Rakudo by doing: + + nmake install + +This will also precompile all modules and install binaries like C. + +=item Step 6 + +Finally create the MSI package. + + nmake msi + +(Note if you are using Strawberry Perl's GCC use C at this point) + +Depending on your architecture you either rename that msi to: + + rakudo-star-YYYY.MM-x86 (no JIT).msi + +or: + + rakudo-star-YYYY.MM-x86_64 (JIT).msi + + +=item Step 7 + +Delete your C folder and make sure it got deleted. Then run the just +created installer, and do some sanity tests: + + perl6 -e "say $*KERNEL.bits" + zef list --installed + zef install openssl + +If you are using Strawberry Perl then move its directory temporarily to a +different name in order to check all DDLs are correctly installed in the +C folder. + +=item Step 8 + +Stop the release process if step 7 failed. Post any issues to the irc channel +or mailing list. + +=item Step 9 + +Generate a SHA256 sum eg. + + $ sha256sum "rakudo-star-YYYY.MM-x86_64 (JIT).msi" | cut -f1 -d" " > "rakudo-star-YYYY.MM-x86_64 (JIT).msi.sha256.txt" + +=item Step 10 + +Upload the msi package to L and L: + + scp "rakudo-star-YYYY.MM-x86 (no JIT).msi" rakudo@rakudo.org:public_html/downloads/star + scp "rakudo-star-YYYY.MM-x86 (no JIT).msi" rakudo@www.p6c.org:public_html/downloads/star + +If you don't have permission to do this step, please ask one(pmichaud, jnthn, +masak, PerlJam/perlpilot, tadzik, moritz) on C<#perl6> to do it for you. + +Also upload the sha256 sum eg. C + +=item Step 11 + +Publicize the msi packages in the appropriate places. These include: + +=over 4 + +=item * rakudo.org + +=item * #perl6 + +=back + +=item Step 12 + +You're done! Celebrate with the appropriate amount of fun. + +=back + +=cut diff --git a/tools/star/mac-dmg.pod b/tools/star/mac-dmg.pod deleted file mode 100644 index 7ebc64a..0000000 --- a/tools/star/mac-dmg.pod +++ /dev/null @@ -1,142 +0,0 @@ -=head1 Guide to building DMG packages - -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. The dmg packages are based -on these Star releases. - -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, and/or -MoarVM. The goal is to balance end-user stability needs with -progress being made on the compiler, modules, and other runtime -components. - -=head2 Steps to create an DMG package - -A C<.dmg> is a file extension used for an Apple Disk Image which is the most -popular way of running an installer on the Mac desktop - -If this is your first time releasing, B. That way you can ask questions and clear up any 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. - -=over 4 - -=item Step 0 - -Download and install C from Apple if you don't already have the C C -compiler installed. This process was tested on OS X 10.11.x as a build system -using clang-700.1.76 and the result is known to run on as least far back as OS -X 10.9 (and probably further). - -=item Step 1 - -Use your browser to download the latest star release, replace YYYY.MM by year and month: -https://rakudo.perl6.org/downloads/star/rakudo-star-YYYY.MM.tar.gz - -Unpack this C<.tar.gz> to your hard disk. You will get a folder C, again -YYYY.MM is year and month of the star release. - -=item Step 2 - -Change the path to the directory created in the previous step, and run: - - cd ports/darwin_dmg - perl package_darwin_dmg.pl --build -v YYYY MM - -This should automatically compile the MoarVM version of star and all modules and create the C<.dmg> - -In theory this all that needs doing and you can jump to step 4 below. - -=item Step 3 - -Watch the scrollback for errors. - -If the build is interrupted you will have to manually C in the top -level directory before rerunning the previous step. - -Note the C<--build> option will automatically delete the binary destination -directory of C if it exists before running but leaves it in -place after finishing. - -Omitting the C<--build> option will just rebuild the C<.dmg> from C which is useful when debugging the final stage of C<.dmg> build since it's much faster. - -=item Step 4 - -A correct build will create C - -To sanity test - - open Temp_build/Rakudo-Star-YYYY-MM.dmg - -This should automount C and open a Finder window with a -background image of Camelia and "Drag the Rakudo Folder to Applications" -containing a README.txt, a Rakudo folder, Docs folder and a folder representing -a sym link to Applications. - -Delete the directory used to create the C<.dmg>. - - rm -rf /Applications/Rakudo - -Now dragging the C folder to the Applications Link folder (with arrow) -should repopulate C. - -Append your C as suggested in the C and look for reasonable output -from the following kind of commands. - - perl6 -e "say 'hello'" - zef list --installed - p6doc -l - -=item Step 5 - -Stop the release process if you see serious issues with no obvious fix and post -them to the IRC channel or mailing list. If you alter scripts recommit them. - -=item Step 6 - -Generate a SHA256 sum: - - sha256sum rakudo-star-YYYY.MM.dmg | cut -f1 -d" " > rakudo-star-YYYY.MM.dmg.sha256.txt - -=item Step 7 - -Generate a GPG signature for the DMG file: - - gpg --armor --detach-sig rakudo-star-YYYY.MM.dmg - -This will create C. - -=item Step 8 - -Upload the dmg and SHA256 to L: - - rsync -avz rakudo-star-YYYY.MM.dmg* rakudo@www.p6c.org:public_html/downloads/star - -If you don't have permission to do this step, please ask one(pmichaud, jnthn, -masak, PerlJam/perlpilot, tadzik, moritz) on C<#perl6> to do it for you. - -=item Step 9 - -Publicize the dmg packages in the appropriate places. These include: - -=over 4 - -=item * rakudo.org - -=item * #perl6 - -=back - -=item Step 10 - -You're done! Celebrate with the appropriate amount of fun. - -=back - -=cut diff --git a/tools/star/release-guide.pod b/tools/star/release-guide.pod deleted file mode 100644 index 584ee17..0000000 --- a/tools/star/release-guide.pod +++ /dev/null @@ -1,350 +0,0 @@ -=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. 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 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 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 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 Step 3 - -Run C 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 to add -its repo to the modules/ directory. Also add the module directory -name to the C 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 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. 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 and C 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 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, C, or -C, 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. 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 - -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 and L: - - $ scp rakudo-star-2012.08.tar.gz rakudo@rakudo.org:public_html/downloads/star - -Also upload the detached signature eg. C -and sha256 sum eg. C - -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 in the C and to C 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 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 - -=item * L - -=item * Reddit: L, L, -and L - -=item * L - -=item * L - -=back - -=item Step 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 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 diff --git a/tools/star/windows-msi.pod b/tools/star/windows-msi.pod deleted file mode 100644 index 8674c22..0000000 --- a/tools/star/windows-msi.pod +++ /dev/null @@ -1,155 +0,0 @@ -=head1 Guide to build MSI packages - -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. The MSI packages are based -on these Star releases. - -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, and/or -MoarVM. The goal is to balance end-user stability needs with -progress being made on the compiler, modules, and other runtime -components. - -=head2 Steps to create an MSI package - -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. - -=over 4 - -=item Step 0 - -Download and install WiX Toolset, if needed adjust the PATH environment -variable to point to its bin directory. The tools C, C and C -should be available now. - -Install ActivePerl and make sure it is in C. C should give a -sensible output. - -If you do not have the C compiler C installed yet, install the Microsoft -Visual C++ Express for version 2010 or perhaps newer. - -Finally, install the Windows Software Development Kit (SDK) for your Windows -version. - -An alternative to ActivePerl and the Microsoft toolchain is to use Strawberry -Perl which ships with GCC and a mingw toolchain. Run these tools under C -and replace all following references to C by C. - -=item Step 1 - -Make sure there is no C directory, as this will be our installation -target. If there is one, remove it, perhaps after creating backup. - -=item Step 2 - -Use your browser to download the latest star release, replace YYYY.MM by year -and month: https://rakudo.perl6.org/downloads/star/rakudo-star-YYYY.MM.tar.gz - -Unpack this C<.tar.gz> to your hard disk. You will get a folder -C, again YYYY.MM is year and month of the star release. - -=item Step 3 - -Run the Command Line for Visual Studio from the start menu. Alternatively you -can run C followed by C. - -In either case, this should return a valid path: - - echo %VSINSTALLDIR% - -=item Step 4 - -Change the path to the directory created in step 2, and run: - - perl Configure.pl --prefix=C:\rakudo --gen-moar - -This will create a Makefile and will start to compile the MoarVM backend. - -=item Step 5 - -Compile NQP and Rakudo by doing: - - nmake install - -This will also precompile all modules and install binaries like C. - -=item Step 6 - -Finally create the MSI package. - - nmake msi - -(Note if you are using Strawberry Perl's GCC use C at this point) - -Depending on your architecture you either rename that msi to: - - rakudo-star-YYYY.MM-x86 (no JIT).msi - -or: - - rakudo-star-YYYY.MM-x86_64 (JIT).msi - - -=item Step 7 - -Delete your C folder and make sure it got deleted. Then run the just -created installer, and do some sanity tests: - - perl6 -e "say $*KERNEL.bits" - zef list --installed - zef install openssl - -If you are using Strawberry Perl then move its directory temporarily to a -different name in order to check all DDLs are correctly installed in the -C folder. - -=item Step 8 - -Stop the release process if step 7 failed. Post any issues to the irc channel -or mailing list. - -=item Step 9 - -Generate a SHA256 sum eg. - - $ sha256sum "rakudo-star-YYYY.MM-x86_64 (JIT).msi" | cut -f1 -d" " > "rakudo-star-YYYY.MM-x86_64 (JIT).msi.sha256.txt" - -=item Step 10 - -Upload the msi package to L and L: - - scp "rakudo-star-YYYY.MM-x86 (no JIT).msi" rakudo@rakudo.org:public_html/downloads/star - scp "rakudo-star-YYYY.MM-x86 (no JIT).msi" rakudo@www.p6c.org:public_html/downloads/star - -If you don't have permission to do this step, please ask one(pmichaud, jnthn, -masak, PerlJam/perlpilot, tadzik, moritz) on C<#perl6> to do it for you. - -Also upload the sha256 sum eg. C - -=item Step 11 - -Publicize the msi packages in the appropriate places. These include: - -=over 4 - -=item * rakudo.org - -=item * #perl6 - -=back - -=item Step 12 - -You're done! Celebrate with the appropriate amount of fun. - -=back - -=cut -- cgit v1.1