Release guide

How SliTaz is released: the rolling cooking ISOs, a release candidate, a stable version and the tools of the project. Everything goes through Mercurial: a release is a set of tags and pushes, the build host cooks and publishes what the repositories say.

Channels and mirror layout

SliTaz follows the Stable + Cooking model on two architectures (i486 and x86_64). The mirror is laid out by architecture first:

<arch>/cooking/packages            rolling packages, cooked from the wok
<arch>/cooking/iso                 cooking and release candidate ISOs
<arch>/stable/<version>/packages   frozen packages of a stable release
<arch>/stable/<version>/iso        stable ISOs

slitaz-release, the checker

slitaz-release (repository slitaz-dev-tools) tells what a release still needs. It is a dry run: it reads the local repositories and over SSH, the build host and the Mercurial host, then prints what is ready and what is left, with the command for each item. It never writes anything: tagging, copying a wok or creating a mirror directory stays a human decision, one step at a time.

$ slitaz-release 5.1 --rc=5.1-rc1     # a release candidate on cooking
$ slitaz-release 5.1                  # a stable release
$ slitaz-release 5.1 --no-net         # local checks only
SliTaz release check: stable 5.1

Tags
[todo] wok not tagged 5.1 (latest: 5.0)
         -> hg -R wok tag 5.1 && hg -R wok push
Release notes
[ ok ] relnotes.en.html present
[ ok ] relnotes have a known issues section
...
Not ready: 6 item(s) left for stable 5.1

Run it before starting, after each step and until it says Ready. Options: --repos=DIR and --wok=DIR for the local clones and the MARMITE and FOYER variables for the SSH commands.

Cooking ISOs

Cooking is a rolling release: a new set of ISOs is built from the mirror whenever the packages are worth it. ISOs are built with metier for both architectures, from the flavors:

$ metier flavors
$ metier build core-x86_64          # 64-bit, the arch comes from the flavor
$ metier build core                 # 32-bit

The files are named slitaz-<flavor>-<arch>-cooking.iso. Before publishing a set to <arch>/cooking/iso:

Release candidate

  1. Freeze. Fixes only in the wok; one heavy change at a time, announced before it is cooked.
  2. Release notes. Write releases/<version>/relnotes.en.html in slitaz-doc, with a Known issues section. They are published on doc.slitaz.org.
  3. No tag, no version string. Only stable releases are tagged and /etc/slitaz-release keeps saying cooking since the packages are cooking ones. A candidate is traced by the revisions of the wok and flavors and by the package lists of its ISOs: write them in the announcement.
  4. ISOs. Give the release name to metier:
    $ metier build core-x86_64 --release 5.1-rc1
      -> slitaz-5.1-rc1-core-x86_64.iso
    
  5. Validate and publish like a cooking set in <arch>/cooking/iso.
  6. Announce. Download page and news on the website, forum, DistroWatch.

Stable release

A stable release is cooking at a known point: tagged, copied to its own repositories, frozen on its own mirror path and built into official ISOs. Follow the steps in order, with slitaz-release <version> between each.

1. Release notes and documentation

Finish releases/<version>/relnotes.en.html in slitaz-doc: new features, package updates, known issues, upgrade instructions. French, German and Portuguese notes are optional. The handbook of the same repository is shipped in the stable desktop ISOs by the slitaz-handbook package, built on the release tag.

2. Tag the repositories

Tag the cooking wok, the flavors and the documentation at the release point and push:

$ for r in wok flavors slitaz-doc; do
    hg -R $r pull -u && hg -R $r tag <version> && hg -R $r push
  done

3. wok-stable and flavors-stable

On the Mercurial host, archive the previous wok-stable and flavors-stable, then replace them with the wok and the flavors at the release tag. From now on the two branches live apart: cooking goes on toward the next version.

4. Version string, in wok-stable only

/etc/slitaz-release comes from slitaz-base-files. It says cooking in the wok and the version in wok-stable:

$ echo <version> > rootfs/etc/slitaz-release

Bump the slitaz-base-files package in wok-stable so the stable cooker rebuilds it.

5. Flavors of the stable release

In flavors-stable, the files that point to cooking (var/lib/tazpkg/mirror, etc/slitaz-release) point to <arch>/stable/<version>/packages and to the version. Add slitaz-handbook to the desktop flavors.

6. Mirror path

Create the same layout for both architectures:

<arch>/stable/<version>/packages
<arch>/stable/<version>/iso

7. Stable cooker on the build host

One stable cooker per architecture, a copy of the cooking one made at the release so its packages and logs are kept. It is replaced by the next stable release. Then:

8. Stable ISOs

The stable channel of metier needs the release name: it reads <arch>/stable/<version> on the mirror and names the files after the release.

$ metier build core-x86_64 --channel stable --release 5.1
  -> slitaz-5.1-core-x86_64.iso

Build every flavor of the set on both architectures, validate them like a cooking set and publish them with their .md5 in <arch>/stable/<version>/iso.

9. Website and announcement

Update the download pages (<lang>/get/index.php and the home pages), publish a news in every language that has one, then announce on the forum, DistroWatch and the social accounts.

Reminders

Releasing a SliTaz tool

The tools of the project (spk, cookutils, tazinst, metier...) are released from Mercurial, with a tag and a receipt update. The build host cooks the tarball of the tag (archive/$VERSION.tar.gz on hg.slitaz.org): a commit made after the tag is not shipped until the next tag. Here for spk 1.0:

$ cd spk
$ hg pull -u
  (bump the version in the sources, commit)
$ hg tag 1.0
$ hg push

Then update the receipt in the wok, cook it locally and push:

$ cd ../wok
$ hg pull -u
$ vi spk/receipt          # VERSION="1.0"
$ cook spk
$ hg commit -m "spk: update to 1.0"
$ hg push

The Cooker picks the commit, builds the package and publishes it on the mirror for both architectures. Check its log there.