RFC: Een nieuwe versiebeheerstrategie voor Discourse

[schneeland]

@RGJ

It’s not about when the theme/plugin author pushes a fix, it’s about when Discourse core has a security fix.

Ok, but I think then I understand the problem even less

Ultimately, it doesn’t really matter as per @david‘s latest comments, so just to wrap it up.

The proposed model is monthly release, plus 2 esr versions, so e.g. for 2026:

• 2026.1
• 2026.2
• 2026.3
• …
• 2026.8
• 2026.9
• 2026.10
• …

So assuming we are in October 2026 and .2 and and .8 are esr versions, that means 4 supported versions.

And my thought was. Wouldn’t it be easier to basically have quarterly versions, i.e. for 2026:

• 2026.1
• 2026.2
• 2026.3
• …

And still only the current one and the previous release would be supported, so in October 2026, it would be 2.

And the whole reasoning was that maybe this would make it easier for both developers and users. But as mentioned above: @david has clarified that less frequent releases are not an option.

[schneeland]

@david

With the current launcher tooling, and this new branch structure, you could have control over upgrade timing by doing something like:

…

But manually editing that app.yml every month is really not ideal, so hopefully we’ll be able to design a system which makes the process more user friendly.

Understood. That is roughly how I expected it. Indeed, in this case a bit of tool support would be nice at least mid-term.

The way I conceptualise it, is: you are on a specific release channel (latest, release, esr), and usually you would relatively quickly move to the next release, so getting a message and/or notification when the new release is available and having a single command to switch to it would be neat. And for cases, in which you have delayed the adoption of a new release, it would also be nice to be reminded when the currently used release becomes obsolete/unsupported. Bonus points if the respective tool could also let you switch release channels quickly

But I understand if that’s not the top priority right now, and you still recommend people to stay on test-passed/latest.

@david

We’re trying to strike a balance here between the velocity of Discourse development, and the stability for people with extensive customizations. Having a 3+ month delay on getting features into the hands of our customers isn’t an option. If anything, monthly is on the slow side for us.

I see. In the context of my work, getting out a feature to customers is considered “fast”

Also, as mentioned above, my thought was that moving to a quarterly schedule would actually make your life (and the life of plugin/theme developers) easier, because there’s less branches under maintenance. So if that’s not the case, then I guess that really doesn’t make sense for you

[per1234]

I don’t see any benefit to this year-based versioning scheme you propose. Stick with the SemVer compliant version numbers!

[mcwumbly (Dave McClure)]

SemVer itself isn’t really designed for large applications. I understand it to be much more targeted at libraries consumed by software, and in particular, the version numbering logic is built around the package’s API.

We could apply semver to our API(s), though. Having stronger guarantees around the APIs that Discourse exposes is certainly a worthwhile conversation to have, but I think it’s separate from this one.

Now, I understand you didn’t say we should be compliant with semver – you just said we should stick with using numbers that are compliant with the numbering system specified by semver.

1. A normal version number MUST take the form X.Y.Z where X, Y, and Z are non-negative integers, and MUST NOT contain leading zeroes. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically. For instance: 1.9.0 → 1.10.0 → 1.11.0.

I think the “leading zeroes” suggestion is the only thing that we would be breaking from if we go that route.

Otherwise, I think any semver library would still be able to parse the version numbers we’re suggesting and order them properly.

All that aside, can you share more about why you think being compliant with a semver numbering system has value?

[pfaffman (Jay Pfaffman)]

@mcwumbly

I think the “leading zeroes” suggestion is the only thing that we would be breaking from if we go that route.

The OP says that you’re not using leading zeros, if I understand correctly.

@david

e.g. the first release of 2026 would be v2026.0, next would be v2026.1, etc.

I think also a compelling reason to use leading zeros (sorting by versions) has been proposed. Are leading zeros the current plan? (I still like month-versions rather than serial versions).

[per1234]

The point of SemVer is that the version number should communicate some useful information. The only information communicated by your proposed scheme is the earth’s orbit around the sun. That information is not very useful to the consumer of the software.

If for some reason I did want to know the date of the release, I would look at the release and get the full date.

@mcwumbly

SemVer itself isn’t really designed for large applications. I understand it to be much more targeted at libraries consumed by software, and in particular, the version numbering logic is built around the package’s API.

Not really. The point is to communicate the nature of the release to the user.

If the release is a patch version bump, this is communicating that the changeset doesn’t contain anything that is expected to affect the workflow of the users of the software.

If the release is a minor version bump, this is communicating that the changeset includes the addition of new user facing components, but nothing that will break existing workflows of the users of the software.

If the release is a major version bump, this is communicating that the changeset includes changes that may break existing workflows of the users of the software.

The determination of which of the version components should be bumped is more clear cut in a software product that has a single user interface, but the principles remain the same even for a software product like Discourse where there are a variety of levels of interfaces and types of consumers (e.g., plugin developers, API consumers, forum staff, end users).

Even if the choice of which component to bump is a bit more subjective in this software project, it still results in the version number having meaning instead of just being some arbitrary number, as is the case with your proposal.

[RGJ (Richard - Communiteq)]

@pfaffman

The OP says that you’re not using leading zeros, if I understand correctly.

I proposed that a few posts up.

@per1234

version number having meaning instead of just being some arbitrary number, as is the case with your proposal.

Contrary to semver, the proposed version numbering scheme makes it immediately clear if a version is still supported (like Ubuntu). Since that depends on the earth’s orbit around the sun as well, this actually makes sense.

@per1234

If the release is a major version bump, this is communicating that the changeset includes changes that may break existing workflows of the users of the software.

This is clearly targeted towards packages and libraries. Any discourse release includes changes that may break existing workflows of the users of the software. I’ve even seen security patches do that. Semver is not usable for complex applications.

@per1234

@mcwumbly

the version numbering logic is built around the package’s API.

Not really. The point is to communicate the nature of the release to the user.

Yes really, see

Once you identify your public API, you communicate changes to it with specific increments to your version number.

[nickrsan (Nick S)]

@Ed_S

have good descriptions of how to perform them as smoothly as possible.

Just to emphasize a point that might get lost, I think Discourse does great here. One improvement would be to at least highlight the topics you’ve already written that describe changes and potential breakage within that upgrade cycle. For example, with the 3.5 release, I had to open the release notes, click through to the blog, and then happen to click on the link about bundling plugins with Discourse core in order to catch that detail that leaving those plugins within my config file could impact upgrades.

It’d be great to pull those kinds of notes out onto a page/topic for ESR releases, even if it’s just a set of links to existing topics that should be reviewed prior to performing an ESR upgrade.

This may be beyond the scope of this thread though - my feedback on the versioning change is that I welcome it and appreciate the transparency here. I think this would be a great improvement that would simplify things while giving us more options for self-hosting.

Thank you!

[pfaffman (Jay Pfaffman)]

@RGJ

I proposed that a few posts up.

Yes, and it’s such a good idea that I think the op should be edited to reflect that!

[mcwumbly (Dave McClure)]

The leading zeroes and whether or not to aim for synchronization with months more explicitly is being considered. @david will share an update once the group working on this arrives at a decision.

[per1234]

@RGJ

the proposed version numbering scheme makes it immediately clear if a version is still supported

That is not the important information for a forum maintainer evaluating a new release.

@RGJ

Yes really

No, really. You are missing the actual point of SemVer by refusing to understand that “API” actually just means the interface. There is absolutely no reason the spirit of SemVer can not be used in versioning of any type of software.

[mcwumbly (Dave McClure)]

I think we’re going to have to agree to disagree on this point @per1234.

Here’s a related discussion on the GitHub repository for semver with a response from one of the maintainers:

Semver is not really useful for “end-user apps,” it is more useful for libraries that people use as dependencies for their projects.

[elmuerte]

It does not really matter if it is a library or larger application. A semantic versioning scheme (like semver) works perfectly well for large application. It can even be used for a collection of applications bundled into a platform, but here it becomes quite difficult to tackle.

The main question is if you are going down the route of supported depreciation in one release and only removal of it in the next major. Having deprecated, but supported functionality, can take quite a bit of effort. When you are going to make changes to your persisted data model deprecating can often become impossible. If that happens you cannot even do a minor version with deprecated functionality, and you instantly jump to a next major. This is the part where large application usually have problems. You go from 3.0.0 to 3.0.1 to 4.0.0 because you cannot provide backwards compatibility. If you often have breaking changes sticking to semver adds little value.

Having said that. I much more prefer that construction because it communicates more clearly to developers that there is going to be breaking changes. YYYY.N scheme tells me nothing as a developer, and nothing as an admin.

So the question is, what do you want to communicate with the version? If you want to do 6 feature releases (which might or might not be breaking), and every 6th release will be longer supported with patches; and you do not want to version patch releases. Then X.Y is a suitable scheme where Y=0 is the longer supported one. X would be just a number. The problem is when X is the year, then Y quickly is associated with a month. So newer longer supported releases will be released in January? I always have to look up which Ubuntu version is an LTS, which annoys me.

So what if Discourse simply continues with the current major. The next longer supported version is called 4.0; and then we get 4.1 to 4.5 as feature releases; followed by 5.0 which is the newest longer supported one.

Then you also don’t have that awkward moment where a release is delayed because of a major issue.

You could optionally add a “patch” number if you plan to explicitly release patches (instead of having rolling patch releases). “But then you have x.y.z which is semver”. Well no, it looks like semver, but it is not. Every new “minor” release can be breaking. So I suggest to just stick to X.Y as version scheme with Y=0 → LTS

Version string aside. I do like the new release plan.

[mcwumbly (Dave McClure)]

@elmuerte

If you often have breaking changes sticking to semver adds little value.

Yes, this is where things effectively are today, especially with the flexible theme system.

So I think you’re spot on here:

@elmuerte

“But then you have x.y.z which is semver”. Well no, it looks like semver, but it is not. Every new “minor” release can be breaking.

It also means that our the “major” part of our current version number communicates very little.

So, it felt like 'hey, might as well use a year there to communicate something."

@elmuerte

Version string aside. I do like the new release plan.