diff options
authorpmichaud <pmichaud@pobox.com>2012-08-29 08:29:01 -0500
committerpmichaud <pmichaud@pobox.com>2012-08-29 08:29:01 -0500
commit5c86ef586ae347e59b8ecd296e06b8e845415a05 (patch)
parentf9632ae5ac82c5658554e9833bc48817c576e54f (diff)
Add first version of Star release guide.
1 files changed, 100 insertions, 0 deletions
diff --git a/tools/star/release-guide.pod b/tools/star/release-guide.pod
new file mode 100644
index 0000000..64ce774
--- /dev/null
+++ b/tools/star/release-guide.pod
@@ -0,0 +1,100 @@
+=head1 release_guide.pod - guide to Rakudo Star releases
+Rakudo Star releases are based on Rakudo compiler releases.
+Since some time is often needed for module updates and testing
+after each Rakudo compiler release, the timing of Star releases
+varies from one release to the next.
+Also, while the Rakudo compiler issues monthly releases; Star
+releases are free to choose a longer release cycle. Star releases
+are also free to choose older releases of the compiler, NQP, and/or
+Parrot. 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 monthly release cycle; we
+expect to slow down to quarterly releases again sometime in 2013.
+=head2 Steps to create a release
+=over 4
+=item 1.
+Clone the git@github.com:rakudo/star repository.
+ $ git clone git@github.com:rakudo/star
+=item 2.
+Change to the star repository directory, and edit the first three
+lines of tools/star/Makefile to indicate the desired releases of
+Rakudo, NQP, and Parrot to use. Also change PARROT_REL to be
+"supported" or "devel" depending on the type of Parrot release.
+ $ cd star
+ $ vi tools/star/Makefile
+=item 3.
+Run "make -f tools/star/Makefile" to populate the star directory
+with the needed tarballs and module repositories for building Rakudo Star:
+ $ make -f tools/star/Makefile
+=item 4.
+If there are any new modules to be added, use "git submodule" to add
+its repo to the modules/ directory. Also add the module directory
+name to the modules/MODULES.txt file.
+ $ git submodule add git@github.com:user/acme-example modules/acme-example
+ $ echo acme-example >>modules/MODULES.txt
+ $ git commit . -m "Added acme-example to installed modules."
+=item 5.
+Verify that all of the git submodules are at the desired commit
+for the Star release. (TODO: document how to do this.)
+=item 6.
+If one doesn't already exist, create a release announcement in
+docs/announce/YYYY.MM . 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
+ $ git add docs/announce/YYYY.MM
+ $ git commit docs
+=item 7.
+Update the release number in the README file.
+ $ vi README
+ $ git commit README
+=item 8.
+Create a candidate release tarball:
+ $ make -f tools/star/Makefile release VERSION=2012.08
+This will create a tarball rakudo-star-2012.08.tar.gz in the
+current directory.
+=item 9.
+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-parrot
+ $ make install
+ $ make rakudo-test
+ $ make rakudo-spectest
+ $ make modules-test