Make app versioning more clear #120
Labels
No Label
abra
abra-gandi
awaiting-feedback
backups
bug
build
ci/cd
community organising
contributing
coopcloud.tech
democracy
design
documentation
duplicate
enhancement
finance
funding
good first issue
help wanted
installer
kadabra
performance
proposal
question
recipes.coopcloud.tech
security
test
wontfix
No Milestone
No project
No Assignees
3 Participants
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: coop-cloud/organising#120
Loading…
Reference in New Issue
No description provided.
Delete Branch "%!s(<nil>)"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
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
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:
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)
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? 🙏
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.
🚀 + https://pad.autonomic.zone/SX1Hs84mSDSkU6DZy2KdDA
This passed then, I'll open up some implementation tickets. Thanks all!
EDIT: see https://git.coopcloud.tech/coop-cloud/organising/projects/8 👍