path: root/README.txt

+-----------------+
+ Release process +
+-----------------+

Adding the last commits before the release:
--------------------------------------------
Before a release, we need to make some additional changes in several
repositories.

In this repository:
- We need to edit releasevars.sh and change the RELEASE field to reflect the
  release version we will have, as it is used by the scripts. Additionally we
  might want to fix bugs and/or improve things along the way.

In the vendor/replicant repository:
- We need need to modify REPLICANT_VERSION in config/common.mk and RELEASE
  in sign-build.sh to add the new release version.
- We might also need to modify the ChangeLog or not depending on the type
  of release.

In the manifest repository:
- We need to change all the revisions to use the new tag.

Preparing the source code for tagging:
--------------------------------------
First you need to make sure that all the commits with the changes mentioned
above are in the replicant directory before proceeding because otherwise the
tagging script will tag revisions that don't contain any of these commits.

You also need to make sure that you have no other local modifications that
aren't intended to go in the release for the same reason.

Here's a procedure you can follow to do that very fast:
- save the commits you have on top, like the "last commits before the release"
  which were discussed previously.
- move the .repo directory outside of the replicant directory
- delete the replicant directory
- re-create the replicant directory
- move the .repo directory in it
- re-run the repo init and repo sync commands. This will re-use the .repo cache
  which will speed up a lot the download time.
- re-import all the commits you need to add on top of the existing source code.

Make sure that the manifest commits are added in the git repository that is
checked out in manifest/ as the tagging script will use that to push the tags
for the manifest.

This is not the only way to do it. If you have other ideas, feel free to send
patches to add them in this README as well.

Tagging the source code:
------------------------
Once this is done we can tag the various repositories with releasetag.sh.

This script will tag all the repositories but the manifest, so it expects
all repositories to be mirrored on the Replicant git server.

If you build Replicant on a machine that cannot push the code, for instance
because it doesn't have access to your ssh keys, you can simply export the
Replicant source directory with sshfs to your main computer which has all the
access and run the releasetag.sh from it.

Building the source:
--------------------
Once the tagging is done, you need to re-download the source code again from the
new manifest tag as tools like release.sh expect the manifest to have the release
tag.
Doing it from scratch will make sure that the repositories are fetchable and
that nothing went wrong.

Once this is done, you can finally start building all the images with
releasebuild.sh. The build process can many hours on an older computer, so it's
a good idea to plan that ahead. For instance, if your build computer is noisy
and that its noise can prevent you from sleeping, you might want considering
launching the build as soon as you wake up the morning to have it finished
before you need to go to sleep, or if it's possible you might also want to
consider moving that computer before starting the build.

At the time of writing, around the end of the build of the first target, it
will ask you some information for a certificate, so make sure to be around
as that part is interactive.

Then it will proceed for many hours uninterrupted if everything goes fine.

You can checks the build logs in logs/ to see if the build has finished.

Releasing the images:
---------------------
When the build is done, you can finally use the the release.sh script to
populate the final directory with  all the files to release.

For instance for releasing Replicant 6.0 0004 RC2 I used the following:
$ release.sh replicant-6.0 replicant-6.0-0004-rc2

The replicant-6.0 directory contained the Replicant source code and
replicant-6.0-0004-rc2 was an empty directory.

This script can take a long time if the connection to your builder is slow, as
this downloads all the images.

You need to sign the images with the release.sh script. I used the following
for the replicant-6.0-0004-rc2 release:
$ release.sh replicant-6.0 replicant-6.0-0004-rc2 signatures

The signature is done as a separate process to enable use cases where the
connection to the build server is slow and gpg is setup to be run interactively
(for instance by typing a password).

You can then push that directory to the FTP server and run the FTP server
trigger script when all the files have been copied.

Announcing the release:
-----------------------
As releases also need to be announced, it might be a good idea to work on the
release text in parallel.

We typically inform people through both the mailing list and the blog system we
use. At the time of writing, we use WordPress for our blog, which isn't very
adapted to our needs as the drafts are not public. However we wrote a script to
make it easier to review drafts and to publish them on the mailing list.

To use the script, you need to save the html page that contains the blog post,
and use the release_notes.py on it. If the blog post is a draft, you can simply
preview the draft, and save the resulting html page.

In addition to the blog post and the mailing list:
- We might also need to modify the Replicant IRC channel(s) topic(s) to indicate
  the last Replicant version.
- We also need to push a patch to the replicant website (website.git) to do the
  same: the last Replicant version is mentioned on the main page of the
  replicant.us website.

Copyright:
----------
This README is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.