[Replicant] [release-scripts] [PATCH 3/3] Add a README documenting the release process

[Denis 'GNUtoo' Carikli]

This procedure depends on the following commit:
    TODO Tag all repositories
    TODO

Signed-off-by: Denis 'GNUtoo' Carikli <GNUtoo at cyberdimension.org>
---
 README.txt | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 README.txt

diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..4e2b2ee
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,121 @@
++-----------------+
++ 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.
+
+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.
-- 
2.27.0