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-release, the checker
- Cooking ISOs
- Release candidate
- Stable release
- Releasing a SliTaz tool
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
- Cooking is the rolling branch: the
wokandflavorsrepositories, cooked by the build host after each push. - A release candidate stays on cooking: same wok, same packages, same mirror path. Only the ISO names change.
- A stable release has its own everything: the
wok-stableandflavors-stablerepositories, its mirror path and its build chroots. After the release it only receives security and bug fixes.
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:
- build from the published mirror only, never from a local package;
- boot every ISO, as a CD and as a USB key, in BIOS and UEFI;
- install at least one desktop ISO to disk on each architecture;
- upgrade an install of the previous set from the mirror, reboot;
- publish each ISO with its
.md5, then check the sums on the mirror.
Release candidate
- Freeze. Fixes only in the wok; one heavy change at a time, announced before it is cooked.
- Release notes. Write
releases/<version>/relnotes.en.htmlin slitaz-doc, with a Known issues section. They are published on doc.slitaz.org. - No tag, no version string. Only stable releases
are tagged and
/etc/slitaz-releasekeeps sayingcookingsince 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. - ISOs. Give the release name to metier:
$ metier build core-x86_64 --release 5.1-rc1 -> slitaz-5.1-rc1-core-x86_64.iso
- Validate and publish like a cooking set in
<arch>/cooking/iso. - 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:
- its
wok-hgclone pullswok-stable; WOK_URLandFLAVORS_URLin itscook.confuse the-stablerepositories;- its crons run and its packages are synced to
<arch>/stable/<version>/packages.
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
- The circuit never changes: receipt and cook locally, commit and push, the build host cooks and publishes. Nothing is edited or cooked by hand on a server.
- Every write on a server (a tag pushed, a repository replaced, a mirror directory, a cooker) is decided by the release manager, one step at a time.
- After the release, wok-stable only takes security and bug fixes. New versions go to cooking.
- The release is done when
slitaz-release <version>printsReady: stable <version>.
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.