slapos and slapos.package repositories workflows for maintainers
Repositories, Branches and Release Workflow
This document aims define the standard procedure to release SlapOS Software Releases and slapos.cookbook egg.
We have 2 main branches on slapos.git repository master and 1.0.
Developers should merge their changes on master, and some test suites will ensure that the changes are "ok", to be merged into the release candidate (1.0 Branch). Master branch contains unpinned revisions for the ONLY for following sections:
- erp5
- neoppod
- wendelin
- slapos.core
The main reason is to test and use the bleeding edge software for those internal Nexedi development softwares.
Once changes are considered "Fine" (which is a subjective definition for now) the changes are merged into 1.0 and the git revision for the mentioned software are pinned.
A new Software Relase is a tag of 1.0 branch without any additional commits (exception is bug-fixes releases, which is decribed later on this document). The slapos.cookbook eggs follow the same procedure, as it is part of the same respository.
The Absolute Rules
Those rules must be always respected no matter what:
- Developers should only merge/push to Master Branch, never to 1.0 branch
- Master is merged to 1.0 using "update-rc" script, never manually.
- Tags are generated from 1.0 only
- Tags follow the 1.0.<latest>+1 rule
How to work with branches
How to work with master branch
- Master branch is destination of direct commits and merge requests with fixes and features.
- Revisions for eggs and git checkouts do not have to be frozen.
- Master branch does not guarantee repeatability for any commit.
Things to do on master branch:
- accept merge requests
- commit direct fixes
- release of slapos.cookbook (described in section XXX)
How to work with 1.0 branch
- 1.0 branch is source of tagged releases.
- It accepts merges from master and direct commits in order to update revision of tested software (using update-rc script only)
How to merge from master
It shall be done from time to time.
The source commit of master branch shall be chosen, that it is stable for tested software.
Procedure:
git clone https://lab.nexedi.com/nexedi/slapos.git
cd slapos
bash update-rc
# There is a review step, and commands to follow up after indicated by the command.
How to tag software profiles
By tagging the profiles it is possible to obtain frozen version of software profiles, which allow repeatable deployment.
You need to run the command:
git clone https://lab.nexedi.com/nexedi/slapos.git
cd slapos
bash release-sr
# There is a review step, and commands to follow up after indicated by the command.
Related howtos:
- how to update source cache using tests
- how to update binary cache using tests
- how to update playbooks
- how to release playbooks
- how to inform about new tag
How to make fix minor release (Bug fixes on older tags)
In case when released tag had bugs, requiring immediate fix, proceed as follows after finding the TAG to be fixed. Notice this bug fixes tags are untested usually in a large scale and should be used at little as possible.
Use:
git log --no-walk --tags --pretty="%h %d %s" --decorate=full
To find, if is there any fix minor release (X.Y.Z.F), if not construct FIXTAG as X.Y.Z.1, if there is, construct FIXTAG as X.Y.Z.P+1
Proceed:
### Update the variables accordinally
TAG=X.Y.Z
FIXTAG=X.Y.Z.1
###
git clone https://lab.nexedi.com/nexedi/slapos.git
git checkout -b fix-$FIXTAG $TAG
### CHANGE THE FIXTAG
# Cherry-pick the bug fixes or make commits here
git cherry-pick <HASH> <HASH>....
### END OF CHANGES
git tag -am "Release $FIXTAG" $FIXTAG
git push origin $FIXTAG
Related howtos:
- how to update source cache using tests
- how to update binary cache using tests
- how to update playbooks
- how to release playbooks
- how to inform about new tag
How to release slapos.cookbook
If you want to release the slapos.cookbook, you have 2 options:
Only release EGG w/o using it and update stack/slapos.cfg
git clone https://lab.nexedi.com/nexedi/slapos.git
cd slapos
EGG_ONLY=Y bash release-cookbook
# There is a review step, and commands to follow up after indicated by the command output.
Release EGG and update the vesion on stack/slapos.cfg at the same time
git clone https://lab.nexedi.com/nexedi/slapos.git
cd slapos
bash release-cookbook
# There is a review step, and commands to follow up after indicated by the command output.
Do not forget to push everything once it is finished.
Upgrade revertion procedure
Sometimes one learns that new SR on the Rapid.Space catalog is simply bad and it's impossible to fix it fast with hotfix.
Then it's required to archive the SR and tic instance tree upgrade alarm.
Example: Rapid.Space Operator release procedure
Given SR to release, let it be kvm, this is typical scenario of one of Rapid.Space Operators:
- check that test results on master branch for python2 and/or python3 are ok
- in this case as kvm is python3 only, Operator focuses on python3 and gives GO if kvm passes
- merge working commit to the 1.0 branch
- check that test results on 1.0 pass
- tag the 1.0, remember the tag, create needed SR urls
- in case of kvm it is .../kvm/software.cfg and .../kvm/software.cfg?vpsbrute
- binarize the tag
- Operator uses supply to binary caches as described in (XXX-missing DOC!)
- select a machine to make test
- it has to be machine fully accessible by the operator, including SSL certificate with the user owning the machine in order to supply the not yet published SR there
- tests depend on many factors, but one machine is better than none
- Note: Critical moment! Shall be done on beginning of a week
- publish SR
- invoke compute node upgrade alarm
- await for binary download to finish on upgrade_scope/auto compute node
- invoke instance tree upgrade alarm
- await for instance tree upgrade on upgrade_scope/auto instance tree
- BE READY FOR PROBLEMS
- This step is important. Despite a lot of tests, the new SR can create real problems left and right, so be aware of fixing problems.
- after some delay archive old SRs