From 7f7713382f18886e7ca60181891b5cad95e73236 Mon Sep 17 00:00:00 2001
From: Patrick Spek
Date: Mon, 11 Nov 2019 09:52:31 +0100
Subject: Use the .md extension for the release guide
---
docs/guides/release-guide.md | 273 ++++++++++++++++++++++++++++++++++++++++++
docs/guides/release-guide.pod | 273 ------------------------------------------
2 files changed, 273 insertions(+), 273 deletions(-)
create mode 100644 docs/guides/release-guide.md
delete mode 100644 docs/guides/release-guide.pod
diff --git a/docs/guides/release-guide.md b/docs/guides/release-guide.md
new file mode 100644
index 0000000..5bd8ce2
--- /dev/null
+++ b/docs/guides/release-guide.md
@@ -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/release-guide.pod b/docs/guides/release-guide.pod
deleted file mode 100644
index 5bd8ce2..0000000
--- a/docs/guides/release-guide.pod
+++ /dev/null
@@ -1,273 +0,0 @@
-# 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
--
cgit v1.1