This document explains the process to release new Software Release or new version of existing Software Release. Developers should follow it strictly and make sure all steps are well understood to not loose time when working with software releases.
Before starting, make sure to understand the SlapOS architecture and make yourself familiar with both Buildout and Promises.
The following section contains some a rough walkthrough of the steps to follow when creating a new Software Releaes or upgrading an existing one.
A release cannot evolve. It is frozen and time and not allowed to change. SlapGRID will not touch a Release after installing it on a node. However it is also strictly forbidden to evolve a Release, because it will result in conflicting versions potentially being installed on different nodes. Because of this the following rules must be followed:
Eggs must be pinned
When developing, the LATEST version of an egg should be used to ensure software is developed against it. However, once publishing the Software Release, all eggs need to be pinned.
Good Example
[versions]
Flask-Auth = 0.85
apache-libcloud = 1.2.1
cns.recipe.symlink = 0.2.3
Bad Example
[versions]
Repositories have to specify tags
If you deploy a Software Release to a production system it's completely forbidden to use untagged one like git's HEAD. The reason is that in this case your software release will likely change in time and any software build can have unexpected results.
Good Example
https://lab.nexedi.cn/nexedi/slapos/blob/1.0.13/software/erp5/software.cfg
Bad Example
https://lab.nexedi.cn/nexedi/slapos/raw/master/software/erp5/software.cfg
Provide MD5 Sums
Any buildout.cfg
files downloaded by Buildout must have a corresponding MD5 sum.
Good Example
[template-runner]
filename = instance-runner.cfg
md5sum = 04e31ac503753f89510dd412b4680c56
Bad Example
[template-runner]
filename = instance-runner.cfg
Precache resources in Shacache
If you want to release a software release to the public, it's mandatory to pre-compile it and sign it in shacache.org for a minimum set of operating system that you plan to support. Without shacache everything will be compiled from scratch, which may take several hours for a big ERP5 release and can sometimes depend on environmental variables in OS which have a great chance to break the compilation process
slapos.git
A Software Release is developed using a dedicated branch created from master on slapos.git
. Create separate branches for specific, atomic, features and name the branch based on these (don't use your name!). Once the Software Release is finished and reviewed, it can be merged into master where a new tag is created.
$ git clone https://lab.nexedi.com/nexedi/slapos.git
...
$ cd slapos
$ git checkout -b [Software Release]
Start by cloning slapos.git
:
https://lab.nexedi.com/nexedi/slapos.git
and create a new branch based from Master. Each Software Release has its own branch. Development of the Software Release is done on this branch. Make sure to merge master regularly into your branch to make sure it stays up-to-date with latest development.
Ensure, software.cfg
does not contain anything in the [versions]
section except zc.buildout (and maybe some versions of eggs explictly required. It is possible to use
extensions = buildout-versions
to generate a list of versions of eggs when running Buildout (it is part of stack/slapos.cfg
).
[parts]
should only be done when the Software Release is considered finished or ready to be released (working on your branch after merging latest master).
slapos.cookbook
(Unless when working with a PINNED git revision as for ERP5,) if a Software Release includes new of modified recipes from the slapos.cookbook
, it is required to provide separate tests for these recipes. Ones tests are passing, ask for a review before merging into master and then release/request a release of a new slapos.cookbook
version.
Remove any develop=
related part, which will force using published eggs. Then test the Software Release installation (ideally using the branch version on ViFiB). Once the installation finished, the buildout-versions will produce output of versions. Afterwards, test instantation.
Once installation and instantiation work as expected, add versions produced by buildout-versions (see example) and afterwards add your ShaCache certificate (example).
At this point, code needs to be reviewed by the SlapOS team before merging into the Master branch. Once merged, the development branch can be unpinned again, so that the Software Release on the branch can use latest available eggs (goes back into development). After merging, create a new SlapOS tag on Master (slapos-[revision-numner]) and the Software Release is published or updated.
After the Release has been published it should also be included in the official SlapOS catalog and automated testing. When adding it to both lists, one manual install may be required by the developer to fill ShaCache with all required files and ensure everything worked correctly.