From e0416bf1a9bf810e2ca1591b88c9fc4508fd33c5 Mon Sep 17 00:00:00 2001
From: Patrick Spek <p.spek@tyil.nl>
Date: Fri, 1 Nov 2019 11:48:30 +0100
Subject: Update release documentation

---
 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 ++++++++++++++++
 4 files changed, 579 insertions(+)
 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

(limited to 'docs')

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<git submodule> to add
+its repo to the modules/ directory.  Also add the module directory
+name to the C<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."
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<read the whole guide before
+starting>. 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<Xcode> from Apple if you don't already have the C<clang> 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<rakudo-star-YYYY.MM>, 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<make clean> in the top
+level directory before rerunning the previous step.
+
+Note the C<--build> option will automatically delete the binary destination
+directory of C</Applications/Rakudo> 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</Applications/Rakudo> 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<ports/darwin_dmg/Temp_build/Rakudo-Star-YYYY-MM.dmg>
+
+To sanity test
+
+  open Temp_build/Rakudo-Star-YYYY-MM.dmg
+
+This should automount C</Volumes/Rakudo> 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<Rakudo> folder to the Applications Link folder (with arrow)
+should repopulate C</Applications/Rakudo>.
+
+Append your C<PATH> as suggested in the C<README.txt> 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<rakudo-star-YYYY.MM.dmg.asc>.
+
+=item Step 8
+
+Upload the dmg and SHA256 to L<https://rakudo.perl6.org/downloads/star>:
+
+ 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<templates/files.html.ep> 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<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.
+
+=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<heat>, C<candle> and C<light>
+should be available now.
+
+Install ActivePerl and make sure it is in C<PATH>. C<perl -V> should give a
+sensible output.
+
+If you do not have the C compiler C<cl> 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<cmd.exe>
+and replace all following references to C<nmake> by C<gmake>.
+
+=item Step 1
+
+Make sure there is no C<C:\rakudo> 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<rakudo-star-YYYY.MM>, 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<cmd.exe> followed by C<vcvars32.bat>.
+
+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<zef>.
+
+=item Step 6
+
+Finally create the MSI package.
+
+  nmake msi
+
+(Note if you are using Strawberry Perl's GCC use C<build_msi> 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<C:\rakudo> 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<C:\rakudo> 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<http://rakudo.org/downloads/star> and L<https://rakudo.perl6.org/downloads/star/>:
+
+ 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<rakudo-star-YYYY.MM-x86_64 (JIT).msi.sha256.txt>
+
+=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