Based on last few weeks of prototyping and discussions with @ry
Release management design overview
Terminology
-
MergeTB release
refers to a release of artifacts from the MergetB ecosystem
- Could include both OS packages as well as machine images etc.
- Not tightly coupled to an upstream OS release name
Ecosystem Releases
Maintain these channels of releases of the MergeTB ecosystem as a whole:
Release Channel |
Purpose |
oldstable |
Frozen cut of previous production release |
oldstable-updates |
Rolling updates for previous production release |
oldstable-security |
Rolling security-fixes for previous production release |
|
|
stable |
Frozen cut of current production release |
stable-updates |
Rolling updates for current production release |
stable-security |
Rolling security fixes for current production release |
|
|
testing |
Rolling release of candidates for the next production release |
testing-updates |
Mock of rolling updates for next production release |
testing-security |
Mock of rolling security fixes for the next production release |
|
|
unstable |
Rolling release of artifacts unassociated with any previous, future, or current release |
Use code-names for releases of the MergeTB ecosystem as a whole (based on fruit names from Wikipedia):
Release Code Name |
Release Version |
Notes |
tomato |
n/a |
This code name is permanently mapped to the release channel unstable
|
lotus |
n/a |
Placeholder for the mythical non-existent previous stable release |
apricot |
0.x |
Current production release |
banana |
1.x |
Next release candidate (e.g. Merge 1.0 on the roadmap) |
|
|
|
OS Package Releases
Releases of MergeTB operating system packages are traced to the ecosystem-level code-names (above).
The idea being that folks will track the code-name, not the release channel name, in their sources.list.
Debian and Ubuntu
Distribution Names
Mapping from MergeTB release nomenclature to APT/.deb “Distribution” names:
MergeTB -Release Channel |
MergeTB - Release Code Name |
APT - Distribution |
unstable |
tomato |
tomato |
|
|
|
stable |
apricot |
apricot |
stable-updates |
apricot |
apricot-updates |
stable-security |
apricot |
apricot-security |
|
|
|
testing |
banana |
banana |
testing |
banana |
banana-updates |
testing |
banana |
banana-security |
|
|
|
oldstable |
lotus |
lotus |
oldstable-updates |
lotus |
lotus-updates |
oldstable-security |
lotus |
lotus-security |
Repositories
Mapping to MergeTB’s Nexus hosted APT repositories:
MergeTB - Release Channel |
Nexus APT - Repo Name |
Nexus APT - Dist Name |
unstable |
mtb-apt-tomato |
tomato |
|
|
|
stable |
mtb-apt-apricot |
apricot |
stable-updates |
mtb-apt-apricot-updates |
apricot-updates |
stable-security |
mtb-apt-apricot-security |
apricot-security |
|
|
|
testing |
mtb-apt-banana |
banana |
testing-updates |
mtb-apt-banana-updates |
banana-updates |
testing-security |
mtb-apt-banana-security |
banana-security |
|
|
|
oldstable |
mtb-apt-lotus |
lotus |
oldstable-updates |
mtb-apt-lotus-updates |
lotus-updates |
oldstable-security |
mtb-apt-lotus-security |
lotus-security |
Additional assumptions:
- MergeTB will stand up a Sonatype Nexus repository server
- There will be an Nginx reverse proxy for http requests to it
- It will map public requests for
http://apt.mergetb.net
to specific APT repositories hosted by Nexus
Example name mappings that would be done by Nginx:
Release Channel |
Public Nginx URL |
Internal Nexus URL |
tomato |
http://apt.mergetb.net/tomato |
http://<nexus>/repositories/mtb-apt-tomato |
|
|
|
stable |
http://apt.mergetb.net/apricot |
http://<nexus>/repositories/mtb-apt-apricot |
stable-updates |
http://apt.mergetb.net/apricot-updates |
http://<nexus>/repositories/mtb-apt-apricot-updates |
stable-security |
http://apt.mergetb.net/apricot-security |
http://<nexus>/repositories/mtb-apt-apricot-security |
|
|
|
testing |
http://apt.mergetb.net/banana |
http://<nexus>/repositories/mtb-apt-banana |
testing-updates |
http://apt.mergetb.net/banana-updates |
http://<nexus>/repositories/mtb-apt-banana-updates |
testing-security |
http://apt.mergetb.net/banana-security |
http://<nexus>/repositories/mtb-apt-banana-security |
|
|
|
oldstable |
http://apt.mergetb.net/lotus |
http://<nexus>/repositories/mtb-apt-lotus |
oldstable-updates |
http://apt.mergetb.net/lotus-updates |
http://<nexus>/repositories/mtb-apt-lotus-updates |
oldstable-security |
http://apt.mergetb.net/lotus-security |
http://<nexus>/repositories/mtb-apt-lotus-security |
Example sources.list entries
The sources.list
examples below all use the public Nginx URL for the Nexus managed repositories.
Tomato
Permanent “unstable” release channel
deb http://apt.mergetb.net/tomato tomato main
deb-src http://apt.mergetb.net/tomato tomato main
Apricot
Current “stable” release channel
deb http://apt.mergetb.net/apricot apricot main
deb-src http://apt.mergetb.net/apricot apricot main
deb http://apt.mergetb.net/apricot-updates apricot-updates main
deb-src http://apt.mergetb.net/apricot-updates apricot-updates main
deb http://apt.mergetb.net/apricot-security apricot-security main
deb-src http://apt.mergetb.net/apricot-security apricot-security main
Banana
Current “testing” release channel
deb http://apt.mergetb.net/banana banana main
deb-src http://apt.mergetb.net/banana banana main
deb http://apt.mergetb.net/banana-updates banana-updates main
deb-src http://apt.mergetb.net/banana-updates banana-updates main
deb http://apt.mergetb.net/banana-security banana-security main
deb-src http://apt.mergetb.net/banana-security banana-security main
Lotus
Current “oldstable” release channel
Reminder that this is mock only, until banana
is new stable
, and apricot
becomes oldstable
.
deb http://apt.mergetb.net/lotus lotus main
deb-src http://apt.mergetb.net/lotus lotus main
deb http://apt.mergetb.net/lotus-updates lotus-updates main
deb-src http://apt.mergetb.net/lotus-updates lotus-updates main
deb http://apt.mergetb.net/lotus-security lotus-security main
deb-src http://apt.mergetb.net/lotus-security lotus-security main
Packages
The same “logical” artifact may be released as multiple instances of “physical” packages, but these physical packages should be uniquely identifiable via their package versioning.
Multiple versions of these packages can end up in different APT repositories at various times in the packge’s own life cycle.
Workflows
General workflows are as follows:
- Experimental work
- Drafts not intended for a release candidate or as an updates/fix for a previously released candidate, will get
published to the unstable
release channel.
- Releasing the current release candidate
- No package publication happens.
- A new code-name is picked for the new “testing” release and Nexus APT repositories etc. are created for it
- The GitLab ci/cd plumbing is reconfigured to change its aliasing between code names and the release channel
names.
- The code-name currently aliased by
stable
is now aliased by oldstable
- The code-name currently aliased by
testing
is now aliased by stable
- The new code-name for the next “testing” release is now aliased by
testing
- Updates and security fixes for the current released candidate
- General updates get published to the
stable-updates
release channel
- Security fixes get published to the
stable-security
release channel
- In addition, if applicable, they should be published to the
testing
release channel for inclusion in the
next release candidate.
- Updates and security fixes for the previous released candidate
- General updates get published to the
oldstable-updates
release channel
- Security fixes get published to the
oldstable-security
release channel
- In addition, if applicable, they should be published to the
testing
release channel for inclusion in the
next release candidate.
Versioning
In general, follow the Debian package maintainer conventions for “upstream_version” versus “debian_version”.
- The “upstream_version” should be tracable to a GitLab
v<semver>
release tag.
- The source git tags do not include the packaging specific iteration numbers and “debian versions”
- Packages should always explicitly state an iteration number, starting at
1
- Based on advice from Debian maintainer docs etc.
- The “debian-version” should reference Debian/Debian-derivative releases (e.g. Ubuntu) as per the guidelines
Example Source Git Tag |
Target OS |
Example package version |
Example package file name |
v1.0 |
Any Debian or Debian-derived |
1.0-1~1 |
strawman-1.0-1.deb |
v1.0 |
Specific to Debian buster
|
1.0-1~1deb10 |
strawman-1.0-1~1deb10.deb |
v1.0 |
Specific to Debian bullseye
|
1.0-1~1deb11 |
strawman-1.0-1~1deb11.deb |
v1.0 |
Specific to Ubuntu focal
|
1.0-1~1ubuntu0.20.04 |
strawman-1.0-1~1ubuntu0.20.04.deb |
|
|
|
|
Publication
Updates to current stable release channel:
Development Event |
GitLab Event |
Nexus Event |
|
|
|
First releasable draft of the project has accumulated in master |
Maintainer creates release tag v1.0 based on master branch |
|
|
CI/CD job builds deb package files based on the contents of v1.0 tag |
|
|
CI/CD job publishes deb packages to the current unstable repo |
tomato repo gets updated |
|
|
|
Changes are submitted for the next draft |
A merge request is submitted to master branch and accepted |
|
|
|
|
Another releasable draft of has accumulated in master |
Maintainer creates release tag v1.2 based on master branch |
|
|
CI/CD job builds deb package files based on the contents of v1.2 tag |
|
|
CI/CD job publishes deb packages to the current unstable repo |
tomato repo gets updated |
|
|
|
Draft is ready for integration/system testing |
Project maintainer creates releaset tag dist_testing based on v1.2 tag |
|
|
CI/CD job builds deb package files based on the contents of dist_testing tag |
|
|
CI/CD job publishes deb packages to the current testing repo |
banana repo gets updated |
|
|
|
Draft is ready for inclusion in stable-updates |
Project maintainer creates releaset tag dist_stable-updates based on v1.2 tag |
|
|
CI/CD job builds deb package files based on the contents of dist_stable-updates tag |
|
|
CI/CD job publishes deb packages to the current stable-updates repo |
apricot-updates repo gets updated |
|
|
|
Security fixes for current stable release channel:
Development Event |
GitLab Event |
Nexus Event |
|
|
|
A security issue is found for a draft previously published to stable |
A feature branch, sec-issue-N is created based on the git tag of the affected release |
|
A fix for the security issue is submitted |
A merge request is submitted to sec-issue-N branch and accepted |
|
|
|
|
Staging security fix candidate for side-band integration/system testing |
Maintainer creates release tag v1.3 based on sec-issue-N branch |
|
|
CI/CD job builds deb package files based on the contents of v1.3 tag |
|
|
CI/CD job publishes deb packages to the current unstable repo |
tomato repo gets updated |
|
|
|
Draft is ready for inclusion in stable-security |
Project maintainer creates releaset tag dist_stable-security based on v1.3 tag |
|
|
CI/CD job builds deb package files based on the contents of dist_stable-security tag |
|
|
CI/CD job publishes deb packages to the current stable-security repo |
apricot-security repo gets updated |
|
|
|
The security fixes are rolled into current mainline of development |
Maintainer submits a merge request that brings the changes in from sec-issue-N branch |
|
|
to master branch. |
|
|
|
|
Security fixes for oldstable release channel:
Development Event |
GitLab Event |
Nexus Event |
|
|
|
A security issue is found for a draft previously published to oldstable |
A feature branch, sec-issue-N is created based on the git tag of the affected release |
|
A fix for the security issue is submitted |
A merge request is submitted to sec-issue-N branch and accepted |
|
|
|
|
Staging security fix candidate for side-band integration/system testing |
Maintainer creates release tag v1.4 based on sec-issue-N branch |
|
|
CI/CD job builds deb package files based on the contents of v1.4 tag |
|
|
CI/CD job publishes deb packages to the current unstable repo |
tomato repo gets updated |
|
|
|
Draft is ready for inclusion in stable-security |
Project maintainer creates releaset tag dist_oldstable-security based on v1.4 tag |
|
|
CI/CD job builds deb package files based on the contents of dist_oldstable-security tag |
|
|
CI/CD job publishes deb packages to the current oldstable-security repo |
lotus-security repo gets updated |
|
|
|
The security fixes are rolled into current mainline of development |
If applicable, maintainer submits a merge request that brings the changes in |
|
|
sec-issue-N to master branch. |
|
|
|
|
|
|
|