Release process / Branching strategy

[ManiMatter]

@lolimmlost , @jrhager84

hi both

I was wondering if you have any thoughts on the release process/branching strategy.

Currently, we brach out of dev, merge features into dev, which builds the dev image. Eventually, we merge dev into latest, which creates a new version.

this is a process I created because a) I didn‘t know any better, b) as I didn‘t trust my own coding skills and thus wanted to first release to dev to a small audience, before ruining everyone elses life ;)

If you have any ideas how to change the setup to make it better/aligned to best practices/easier to collaborate: keen to hear your ideas!

Also, how often should we push dev to latest?

[jrhager84]

Usually a dev, a canary, and latest could work in the sense that those that want the newest stuff can use the canary branch, and once it settles we can merge into latest. It really depends on stability IMO. If we can grok through tickets, ad-hoc releases are fine if the scope is small. If they're GIANT breaking changes, we would have to be more measured. I think SemVer would help keep that under wraps. People could major version lock if they don't want to deal with breaking changes. And when an RC comes about with breaking changes, we'd increment the major version. 2.x -> 3.x. That way we observe major/minor/patch

I do want to preface that I am currently working on building the repos to submit to TrueNAS and Unraid natively as first-class plugins. I just want the latest branch to stabilize and mature a bit, but I have a local commit waiting to rebase and push. We'd also need icons etc.

[ManiMatter]

The versions currently are bumped automatically on the latest branch using x.y.z format, with x = major, y = minor, z = patch.
If commit includes the words #major or #minor it will bump x or y, else bump patch.

My thinking was to use minor for new features. Patches for bug fixes. and Major for breaking changes.

PS: We don't have to change things if they work, I'm not hung up on it. Just asking what you all feel would make sense / feel more natural, since this is all a bit "self-invented" in absence of better knowledge.

[jrhager84]

That's exactly SemVer (Semantic Versioning). 1st value is major (breaking changes). 2nd is minor (feature enhancement with no breaking changes). 3rd is patch (hotfix/etc)

[lolimmlost]

Current dev -> latest flow works well for the pace we're at. SemVer is already in place via the tag action which is good. Two things I'd be open to for the future:

1. A canary/RC tag for larger changes (like the web UI or the degradation work) so they get soak time beyond dev before cutting a release. Not urgent -- dev already serves that role today -- but worth having if we start shipping more frequently.

2. Pinning image tags to specific versions in compose examples so users can lock to a major version and opt into upgrades. Right now the docs point at "latest" which auto-upgrades on every release.

No strong opinion on changing things just to change them. If jrhager84's TrueNAS/Unraid packaging needs a more structured release cadence we can adapt then.

[ManiMatter]

Any opinion how frequently we should merge dev to latest?

[jrhager84]

Current dev -> latest flow works well for the pace we're at. SemVer is already in place via the tag action which is good. Two things I'd be open to for the future:

1. A canary/RC tag for larger changes (like the web UI or the degradation work) so they get soak time beyond dev before cutting a release. Not urgent -- dev already serves that role today -- but worth having if we start shipping more frequently.
2. Pinning image tags to specific versions in compose examples so users can lock to a major version and opt into upgrades. Right now the docs point at "latest" which auto-upgrades on every release.

No strong opinion on changing things just to change them. If jrhager84's TrueNAS/Unraid packaging needs a more structured release cadence we can adapt then.

Yeah - I'd argue we deprecate the 'dev' tag because that's a highly unstable branch and should not be user-facing. I feel like making canary and latest image tags is appropriate.

[ManiMatter]

I thought radarr/sonarr etc use dev for their nightly builds, and thus thought offering „newest yet potentially unstable“ to users via „dev“ tag.

[jrhager84]

I thought radarr/sonarr etc use dev for their nightly builds, and thus thought offering „newest yet potentially unstable“ to users via „dev“ tag.

dev is super unstable imo - It's the earliest entry-point for ANY issues (including devs). Canary makes it meaningful in my mind. I'd be more comfortable with an opt-in canary branch whereas latest is the common convention for users wanting stable releases. That way - once dev is tested etc. we can push to canary for early bird adoption, and sparing any horrible regressions that we weren't able to repro, we do something like a weekly/monthly update schedule (even if we skip a week/month etc.) it's always at least 1 week's worth of updates etc.

[ManiMatter]

I see your point. „nightly“ as canary tag maybe..

Probably needs a few changes to the github workflows, the „contribute.md“, „readme.md“, and what have you.

Lets pick it up when we get time for it