We’re planning to introduce a new versioning system for Discourse. Our goal is to provide more choice & predictability for community administrators, while maintaining our development velocity. We’re also adjusting some terminology to align better with other software. This document will evolve as we receive comments, begin to implement the system, and then expand use of the new release streams. If you have any comments/suggestions at this stage, please let us know by replying to this topic! Goals Introduce more regular ‘releases’ for Discourse, which provide a balance between speed-of-development and stability Continue to provide approx. 6-monthly releases which are supported for an extended period Provide overlapping support for regular & extended-support releases, so that administrators have more flexibility over update timing, while continuing to receive critical security updates Keep ceremony around ‘releases’ to a bare minimum. As much as possible should be automated, and should not slow down the core developer experience. ESR releases are just the same as any other release. Naming & procedure should match industry standards, so that it’s easier to explain to developers & end-users High-level Overview Cut approximately one release per month. The ‘major’ version is the current year, and the ‘minor’ version increments with each release. The patch version number will be incremented for any backported fixes e.g. the first release of 2026 would be v2026.0, next would be v2026.1, etc. Releases will receive critical fixes for two full release cycles. e.g. support for 2026.0 would continue until 2026.2 is released. Approximately every 6 months, declare one of those releases as an Extended Support Release (ESR). ESR versions remain supported for 2 releases after the next ESR is declared. e.g. if v2026.0 is ESR, and v2026.6 is the next ESR, then v2026.0 support will end when v2026.8 is released. Assuming a monthly cadence, that would be a 2 month overlap in ESR support. Provide critical fixes for latest, the most recent release, the previous release, and any active ESR versions. Rename the tests-passed branch to latest Example graph of support periods over a year: gantt title Discourse Releases and Support Periods (Jan 2026 – Jan 2027) dateFormat YYYY-MM-DD axisFormat %b %Y 2026.0 (ESR) :active, 2026-01-27, 2026-09-29 2026.1 :done, 2026-02-24, 2026-04-28 2026.2 :done, 2026-03-31, 2026-05-26 2026.3 :done, 2026-04-28, 2026-06-30 2026.4 :done, 2026-05-26, 2026-07-28 2026.5 :done, 2026-06-30, 2026-08-25 2026.6 (ESR) :active, 2026-07-28, 2027-01-26 2026.7 :done, 2026-08-25, 2026-10-27 2026.8 :done, 2026-09-29, 2026-11-24 2026.9 :done, 2026-10-27, 2026-12-29 2026.10 :done, 2026-11-24, 2027-01-26 2026.11 :done, 2026-12-29, 2027-01-26 Implementation Each release will have a branch cut from latest. These will be namespaced, and preserved indefinitely. For example, v2026.1 would have a branch named release/2026.1 Each patch release will be tagged. e.g. v2026.1.0, v2026.1.1, etc. The latest release will be tagged release. The latest ESR will be tagged esr. Previous release will be tagged release-previous. Previous active ESR (if any) will be tagged esr-previous. For backwards compatibility, tags matching the existing release streams will be aliased to the closest new equivalent. stable → esr. beta → release. tests-passed → latest. These will be considered deprecated, and we’ll aim to drop some or all of them in the future. In particular, ‘beta’ is problematic because it gives the impression that Discourse is not production-ready. On latest, the version number will be the currently-in-development version, suffixed with -latest. e.g. 2026.3.0-latest Automated Release Process Each month, a GitHub action will open a new PR containing a single commit which bumps the version.rb on main to the next -latest version. Once a human has merged the PR, another GitHub action will detect main moving to the next -latest and cut a branch for the completed release. Essentially, this branch becomes a ‘release candidate’. Another automated PR will be opened against the release branch with an update to remove the -latest suffix from version.rb, and thereby ‘release’ it. Usually, we’ll merge these two PRs in quick succession. But having separate PRs for creating and finalizing the release gives us the option to address any issues in the branch prior to finalizing. %%{init: { 'logLevel': 'debug', 'gitGraph': {'showBranches': true, 'showCommitLabel':true,'mainBranchOrder': 2}} }%% gitGraph checkout main commit id:'version v2026.1-latest' commit id:'...' commit id:'....' branch 'release/2026.1' commit id:'version 2026.1' checkout 'main' commit id:'version v2026.2-latest' Separately, another GitHub actions workflow will watch for any backported commits to release branches. When any are found, a new PR will be generated to bump the patch version on that branch. A human can decide when to merge those PRs. All these automations will automatically keep various tags (release, release-previous, esr, esr-previous, plus backwards-compatibility aliases) up-to-date. Security Fixes Security fix workflow remains largely the same, except that we now need to make the fixes in two of these three new places: latest esr esr-previous :new_button: release :new_button: release-previous :new_button: (Remember, per the earlier illustration, it’s only two of the three because esr-previous is supported, the new esr is the same as release or release-previous, and we drop support for esr-previous when that’s no longer true). When introducing a security fix to latest, a latest-security-fix tag will automatically be moved to that commit. docker_manager will be updated to monitor that tag and prompt admins to update. This allows us to release and notify about security fixes without needing to expedite a version bump. Translations At the moment, the stable and tests-passed branches can be translated in CrowdIn, and the results are regularly integrated. In the new system, we initially plan for latest and release to be translatable in CrowdIn. Ideally, by the time release becomes release-previous or esr, translations will have settled. If there is demand for continuous translations of those versions, then that’s something which could be considered in future. Plugin/Theme Compatibility Increasing the use of non-latest streams of Discourse will increase our dependence on the discourse-compatibility system. So we need some improvements to the compat system. Instead of using a .discourse-compatibility file on main, we could instead support implicit compatibility based on specially-named branches/tags. This should be much easier than juggling commit hashes manually. For example, a plugin could have branches like d-compat/v2026.1 d-compat/v2026.2 d-compat/v2026.3 main (used for any Discourse version which doesn’t have its own branch) When installing a plugin, Discourse can check for a branch matching the current version. If it exists, check that out. Otherwise, check the .discourse-compatibility file. Otherwise, check out the default branch. We can create a public GitHub action which runs on each theme/plugin daily, checks for new Discourse releases, and automatically creates these branches. Each theme/plugin could choose to use this auto-pinning action, or they could go for a more ‘floating’ strategy. discourse.org hosting Initially, our hosted offering will continue to run the latest version of Discourse. In the future, we’ll be exploring options for our enterprise-tier customers to select a ‘release’ version. Standard install defaults Initially, the default will remain latest. Admins will be able to opt-in to the new release stream in the same way that they opt-in to stable at the moment. We may explore easier switches between release streams in future, once the system is more mature.

It’s not about when the theme/plugin author pushes a fix, it’s about when Discourse core has a security fix. Per [图片] david: Approximately every 6 months, declare one of those releases as an Extended Support Release (ESR). ESR versions remain supported for 2 releases after the next ESR is declared. the only difference between release and esr is that esr gets security fixes for 6 + 2 = 8 months.

[图片] schneeland: What’s not quite clear to me yet is how the upgrade process will work for the release and esr branches (latest seems straight-forward). With the current launcher tooling, and this new branch structure, you could have control over upgrade timing by doing something like: v2026.02 released You set version: release/v2026.02 in your app.yml file v2026.03 released You run a rebuild. You still get 2026.02, with any recent security fixes When ready, you switch to version: release/v2026.03 in app.yml 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. [图片] schneeland: my intuition would be that both normal and esr releases receive at least a bit of extra testing The process in the OP does allow us to treat the branches as ‘release candidates’ before actually marking them as a release. I’m not sure exactly if/how we’ll use that capability at this stage - I think it’s something that will evolve as we get used to the new system. [图片] schneeland: Lastly, I am wondering if monthly releases are actually “too fast”. 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. At the moment we still intend to use latest for the majority of our hosting. But of course, for people hosting Discourse themselves, I understand the desire to have less frequent change. So that’s where the ESR releases come in.

[图片] schneeland: My understanding based on the previous posts was that the creation of a release version branch would automatically trigger the creation of a plugin branch for that version It’s up to the plugin/theme author here. Either they can continue with the current strategy, where the main branch of the plugin needs to work with all ‘released’ versions of Discourse. Or they can use the automatic branching strategy, which makes compatibility easier, but also means you may need to do a lot of ‘backporting’ in your plugin in case of any critical bug/security fixes. At any given time, there are three “supported” versions of Discourse, plus latest. So critical fixes will need to be applied in up-to 4 branches.

[图片] 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 :confused: 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.

[图片] 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 :slightly_smiling_face: 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” :sweat_smile: 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 :slightly_smiling_face:

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

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. 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?

[图片] 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).

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.

[图片] 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.

RFC：Discourse 的新版本策略

开发

per1234 2025 年9 月 26 日 16:06 24

我不认为你提出的这种基于年份的版本控制方案有什么好处。请坚持使用符合 SemVer 的版本号！

话题		回复	浏览量
January 2026 Releases Announcements release-notes	15	1843	2026 年2 月 3 日
July 2026 monthly release Announcements release-notes	13	802	2026 年7 月 29 日
Stable branch compatibility with discourse_docker and plugins Self-hosting stable	37	3158	2024 年2 月 3 日
Jumping from 2026.1 ESR to 2026.7 - What I found Product Support	6	473	2026 年9 月 12 日
Enable updates only to a given release UX	28	3578	2017 年1 月 25 日

RFC：Discourse 的新版本策略

相关话题