# How To Upgrade Software Release

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.

# Table of Content

- Upgrading a Software Release

# Upgrading a Software Release

The following section contains some a rough walkthrough of the steps to follow when creating a new Software Releaes or upgrading an existing one.

# Freeze a Release

- Eggs must be pinned
- Repositories have to specify tags
- Provide MD5-Sums
- Precache Resources in Shacache

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

# Rationale

- Start from `slapos.git`
- Work on Branches

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.

# Setup

    $ 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).

# Releasing Recipes

- Merge and Request update of `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.

# Testing

- Use Published Eggs
- Test Software Release Installation
- Test Instance
- Add Versions
- Add ShaCache Certificate

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).

# Release Profile

- Code Review
- Merge to Master
- Unpin development branch
- Create new tag for Master

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.

# Add Software Release to Automated Tests

- Add Software Release to SlapOS Software Release list if not there
- Add Software Release to SlapOS Test Agent list to automate testing

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.

# Thank You

- Nexedi SA
- 147 Rue du Ballon
- 59110 La Madeleine
- France

- nexedi.com/contact