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