Make app versioning more clear #120

New Issue

2021-09-09T10:15:02Z

knoflook commented

2021-09-09 10:15:02 +00:00

We talked with @decentral1se about the app versioning scheme and I'd like to propose an improvement to the current one. Right now we use the main app version to do our own tags, which is good. You want the user to be able to look at our tag and know if they are installing nextcloud 21.0.1 or 21.0.2. If the version of another container changes we just add _1 _2 and so on. Let's take a look at nextcloud

[our version]:
[app name]: [app version]


21.0.2:
nextcloud: 21.0.2
mariadb: 10.5

21.0.2_1
nextcloud: 21.0.2
cron: 21.0.2
mariadb: 10.6

21.0.3
nextcloud: 21.0.3
cron: 21.0.3
mariadb: 10.6

The problem is that the version number doesn't make it clear what kind of change 21.0.2_1 is. Is it a patch? Is it a breaking change? Furthermore, if you miss this version and go straight from 21.0.2 to 21.0.3 you won't even notice something was up. Also, abra has no way of knowing if it can roll back to 21.0.2 from 21.0.3 (it shouldn't because the user might be using cron). According to semver.org it should be able to, because the last number denotes a backwards-compatible bugfix. Also, what if the app we're packaging is a rolling release or doesn't use a sensible versioning system? Or we want to use a specific commit? we'd have versions such as 57bf01, 164ec9, 571bc1 which are not very descriptive.

The solution:
Betversch™ - the Better Versioning Scheme (jk it's just semantic versioning). Looks like that: x.y.z+[main app version].
(x is the MAJOR version, Y is the MINOR version and z is the PATCH)

Start with 1.0.0+[main app version]
backwards-compatible patch in any of the containers? Increment z: 1.0.1+[main app version]
new feature, deprecation of feature? Increment y and reset z: 1.1.0+[main app version]
breaking change? Increment x and reset y and z: 2.0.0+[main app version]

What's awesome is that you can immediately decide on new version if all of the containers use semver, by adding the change in app version to our version. Let's see how this would look with nextcloud:

1.0.0+21.0.2:
nextcloud: 21.0.2
mariadb: 10.5

1.2.0+21.0.2: (cron - new feature, mariadb got a minor version bump, I'd split it into two updates though)
nextcloud: 21.0.2
cron: 21.0.2
mariadb: 10.6

1.2.1+21.0.3: (nextcloud got a bugfix)
nextcloud: 21.0.3
cron: 21.0.3
mariadb: 10.6

It's trivial to decide if you can roll back. What's more, if we version using tags, we can automatically generate changelogs from commits and show them to user before they do an upgrade. Or we can just show the tag description.

The user can also choose what changes do they want to see based on the part of the version that changes (i.e. only show major and minor changes and not patches). Abra can refuse to upgrade between major versions and propose a different upgrade path, ask the user to back up before upgrading or do a dance and then continue.

My point is, this way of versioning is more clear and we'd be using a long established and widely used versioning system that is semver. (semver.org)

We talked with @decentral1se about the app versioning scheme and I'd like to propose an improvement to the current one. Right now we use the main app version to do our own tags, which is good. You want the user to be able to look at our tag and know if they are installing nextcloud 21.0.1 or 21.0.2. If the version of another container changes we just add \_1 \_2 and so on. Let's take a look at nextcloud ``` [our version]: [app name]: [app version] 21.0.2: nextcloud: 21.0.2 mariadb: 10.5 21.0.2_1 nextcloud: 21.0.2 cron: 21.0.2 mariadb: 10.6 21.0.3 nextcloud: 21.0.3 cron: 21.0.3 mariadb: 10.6 ``` The problem is that the version number doesn't make it clear what kind of change 21.0.2_1 is. Is it a patch? Is it a breaking change? Furthermore, if you miss this version and go straight from 21.0.2 to 21.0.3 you won't even notice something was up. Also, abra has no way of knowing if it can roll back to 21.0.2 from 21.0.3 (it shouldn't because the user might be using cron). According to semver.org it should be able to, because the last number denotes a backwards-compatible bugfix. Also, what if the app we're packaging is a rolling release or doesn't use a sensible versioning system? Or we want to use a specific commit? we'd have versions such as 57bf01, 164ec9, 571bc1 which are not very descriptive. The solution: Betversch™ - the Better Versioning Scheme (jk it's just semantic versioning). Looks like that: `x.y.z+[main app version]`. (x is the MAJOR version, Y is the MINOR version and z is the PATCH) Start with 1.0.0+\[main app version\] backwards-compatible patch in any of the containers? Increment z: `1.0.1+[main app version]` new feature, deprecation of feature? Increment y and reset z: `1.1.0+[main app version]` breaking change? Increment x and reset y and z: `2.0.0+[main app version]` What's awesome is that you can immediately decide on new version if all of the containers use semver, by adding the change in app version to our version. Let's see how this would look with nextcloud: ``` 1.0.0+21.0.2: nextcloud: 21.0.2 mariadb: 10.5 1.2.0+21.0.2: (cron - new feature, mariadb got a minor version bump, I'd split it into two updates though) nextcloud: 21.0.2 cron: 21.0.2 mariadb: 10.6 1.2.1+21.0.3: (nextcloud got a bugfix) nextcloud: 21.0.3 cron: 21.0.3 mariadb: 10.6 ``` It's trivial to decide if you can roll back. What's more, if we version using tags, we can automatically generate changelogs from commits and show them to user before they do an upgrade. Or we can just show the tag description. The user can also choose what changes do they want to see based on the part of the version that changes (i.e. only show major and minor changes and not patches). Abra can refuse to upgrade between major versions and propose a different upgrade path, ask the user to back up before upgrading or do a dance and then continue. My point is, this way of versioning is more clear and we'd be using a long established and widely used versioning system that is semver. (semver.org)

knoflook added the documentation design labels 2021-09-09 10:15:02 +00:00

knoflook added this to the (deleted) milestone 2021-09-09 10:15:17 +00:00

femmefaytale referenced this issue from toolshed/abra

2021-09-09 12:54:26 +00:00

Make app versioning more clear #96

femmefaytale closed this issue

2021-09-09 12:57:05 +00:00

femmefaytale reopened this issue

2021-09-09 13:01:05 +00:00

decentral1se added this to the (deleted) milestone 2021-09-09 14:25:21 +00:00

decentral1se referenced this issue

2021-09-09 14:31:37 +00:00

How to communicate config/underyling service changes using the n+1 naming scheme #58

knoflook was assigned by decentral1se

2021-09-09 14:40:34 +00:00

decentral1se added this to the Beta release (software) project 2021-09-09 14:40:36 +00:00

decentral1se commented

2021-09-10 08:55:30 +00:00

Thanks for writing this! Betversch++

I've had a good ponder on this. I was so down for "no versioning scheme" but as laid out here, if we can't easily (within the code and by eye) tell which versions represent breaking changes, we're asking for instability.

Having a simple and stable versioning scheme is one of the main things I think we need to get people using this confidentely.

As mentioned, I like that this will make it super simple within abra to determine which upgrades are breaking/non-breaking and showing something like a change log / migration note or something which we can work out. (e.g. a ./logs/1.2.1+21.0.3.txt file in each recipe repo which has a little bit of text in it which we write and abra can show when upgrading so the user knows what to change to not break shit?)

I can imagine a abra app upgrade peertube --ready or something to cover the case where the user has seen a breaking change coming, has migrated their env files or adjusted their app config and is ready for the new upgrade (once we #127 done!).

Anyway, I'm for this.

@3wordchant can you weigh in on this? 🙏

Thanks for writing this! Betversch++ I've had a good ponder on this. I was so down for "no versioning scheme" but as laid out here, if we can't easily (within the code and by eye) tell which versions represent breaking changes, we're asking for instability. Having a simple and stable versioning scheme is one of the main things I think we need to get people using this confidentely. As mentioned, I like that this will make it super simple within abra to determine which upgrades are breaking/non-breaking and showing something like a change log / migration note or something which we can work out. (e.g. a `./logs/1.2.1+21.0.3.txt` file in each recipe repo which has a little bit of text in it which we write and abra can show when upgrading so the user knows what to change to not break shit?) I can imagine a `abra app upgrade peertube --ready` or something to cover the case where the user has seen a breaking change coming, has migrated their env files or adjusted their app config and is ready for the new upgrade (once we [`#127`](https://git.coopcloud.tech/coop-cloud/organising/issues/127) done!). Anyway, I'm for this. @3wordchant can you weigh in on this? 🙏

decentral1se referenced this issue

2021-09-10 09:00:53 +00:00

Support generating tags using our anti-versioning approach #135

decentral1se referenced this issue

2021-09-10 09:50:59 +00:00

Finish app rollback command #146

3wordchant commented

2021-09-16 12:25:14 +00:00

Addition to Betversch++:

Use 0.Y.Z for any apps which aren't using Semver, or not using it consistently, to communicate that we're not making promises about the rollback-a-bility of those.

Addition to Betversch++: Use 0.Y.Z for any apps which aren't using Semver, or not using it consistently, to communicate that we're not making promises about the rollback-a-bility of those.

decentral1se commented

2021-09-16 13:27:53 +00:00

🚀 + https://pad.autonomic.zone/SX1Hs84mSDSkU6DZy2KdDA

:rocket: + https://pad.autonomic.zone/SX1Hs84mSDSkU6DZy2KdDA

decentral1se commented

2021-09-20 14:57:25 +00:00

This passed then, I'll open up some implementation tickets. Thanks all!

EDIT: see https://git.coopcloud.tech/coop-cloud/organising/projects/8 👍

This passed then, I'll open up some implementation tickets. Thanks all! EDIT: see https://git.coopcloud.tech/coop-cloud/organising/projects/8 👍

decentral1se closed this issue

2021-09-20 14:57:25 +00:00

decentral1se referenced this issue