Need a better way to explain what branch to be on, why, and what happens

There is no formal definition of “verfified” that I’m aware of.

All software is potentially buggy.

tests-passed has the most up-to-date commits. beta gets only beta releases. stable gets only stable releases.

tests-passed is what is running on virtually all hosted sites and the vast majority of self-hosted sites.

@mcwumbly – do we have a “what version should I run” document? I searched for a bit and haven’t found one. All I can remember is something like this from stable announcements.


There is

Maybe that is a good start for a topic


That post is also quoted here: Is Discourse always in "beta"?

And we have this topic: Change tracking branch for your Discourse instance

Agree this is a thing we should have a better topic about where we can more clearly reference our recommendation to be on tests-passed.

Separately, I’m somewhat tempted to get rid of beta (I may start a new topic about that).


We should also explain the difference between builds and how to change the build you are on in the install instructions discourse/ at main · discourse/discourse · GitHub. I just scanned it and don’t see any mention of it.


I split this out (I think it’s the first time I’ve done that!), as the poor soul still can’t tell whether it is “dangerous” to upgrade, and this discussion of how to solve the problem of people not knowing whether to upgrade isn’t helping.

Indeed Updates always come before release notes - #7 by jomaxro is a good start, or maybe all that’s needed. Just give it its own sensible title.

But wait!

Maybe Is Discourse always in "beta"?, is what I was looking for (but forgot that it was there to look for it).

The other thing that he asked, which is where he started, and I think is quite reasonable, is “If I’m on the latest beta, why would I need to upgrade?” And the above addresses that fairly directly.

The answer is surprisingly complicated.

Excellent. My job is done here. :supervillain:


I do not think we should. We want people on tests-passed. The official install instructions should lead to a default install with as many settings matching what we want. That includes the branch that is tracked.


There will always be people out there who decide they want to use e.g. the latest stable release. Not having a guide on how to achieve that in the most intuitive place doesn’t make those people go away; it just makes things a bit less convenient for them - and likely sometimes means them coming here to ask, and others spending time answering the question (again and again).

Probably the stronger argument, though, is that the guide can show them how to do it correctly, which means them being able to change back later if they change their mind. If they don’t know, they might end up breaking their install, which will be inconvenient for both them and their community.

If has a section on changing branch, it can clarify what the default is and why, making clear that the default is the most widely used, and the easiest to support.

I am 100% happy for there to be a guide on Meta about how to change branches. I just do not think it belongs in the official install guide, where 95% of people do not care or need to care.

If Basic Bob is trying to install Discourse, he just wants to get through the installation as quickly and easily as possible, so he can work on his new site. Information about changing branches is just going to make him think more, and cause confusion.

Advanced Ally, on the other hand, may be interested in understanding how branches work and which is best for her site. But she’s also likely doing more research prior to installing Discourse, not simply running through the installation guide.


Indeed, as it is we get the occasional topic from users wanting to roll back to beta or stable and it failing.

Putting it in the standard install docs would really open the floodgates, both due to the above and plugin compatibility issues with the older releases.


I agree. On balance I feel like beta confuses people more than it fulfills a utility.

I think it helps to draw a distinction there between things that you use and have meaning internally and things that mean something to third parties. The beta branch is a good example of this. While it may have some internal utility, it has little utility for third parties and sometimes confuses them.

I’d be interested to hear otherwise, but thinking about it now, I can’t recall a serious self-hoster that actually uses beta in any meaningful way. “Basic Bob” doesn’t really know what a branch is and probably doesn’t care (and fair enough). “Advanced Ally” is going to use tests-passed if she’s an individual or SMB, and may use stable (or pin commits) if she’s a medium-sized or large enterprise.

My suggestion would be to keep everything branch-wise exactly as it is but just say publicly “We have two branches you can use: tests-passed (the default and best) and stable (if you know what you’re doing and have a particular need).”


From my side, just having the branch name tests-passed visible next to the version name on the dashboard would be enough of an improvement.

Completely agree. Anyone who wants to take a different branch, will almost always find it.

If they can’t find it with the existing resources(search, standard github project) then are they really equipt with the skills needed to fully understand the difference between the branches, let alone stray from the safety of the default?


Sure, that makes sense. But I feel like we are missing an opportunity to help people understand the distinction between the different options here. I don’t see the harm in telling self-hosters that the default is tests-passed which is ideal for most sites, and ensures you get the latest security fixes and updates. If you are risk averse you can leave it at tests-passed and update only when prompted to do so in the software, or a week or so after you get the prompt. That way other people discover any problems first and they are fixed before you update.

Given the above, are there legit reasons for self-hosters to switch from tests-passed? I guess if your site is heavily modded and will break if core discourse or official plugins are updated, and you don’t trust yourself or your admins to not update? Or if you are setting up a dev or staging environment?

Another place to explain this could be in app.yml which currently is fairly cryptic because it only refers to tests-passed and doesn’t mention the options or when you might switch to a different one.

## Which Git revision should this container use? (default: tests-passed)
#version: tests-passed
1 Like

In my opinion using anything other than tests-passed only really makes sense if you’re on a managed hosting service or: 1) if you have a team managing your community (i.e. you’re a medium to large enterprise); and 2) you have a specific reason for not being on tests-passed, for example you have a multiple customisations that may break.

I would say that both conditions are necessary, because unless you have a team managing your community in the multiple fragile customization scenario your issue is not your branch use but your overall site management (i.e. it’s not sustainable).

Even if both are true, there would be other things to take into account first such as your update policy.

I think the issue is that if you said something like “You can use stable or tests-passed” some people would stick stable in there because it sounds “sensible” when they probably shouldn’t be using it.

Whither beta?

To further the case against the beta branch, in various written and spoken contexts the main confusions it produces are:

  • People normally associate the term “beta” with something more bleeding edge than the “standard”. Not the case here.

  • Some enterprises consider using it because it seems a bit less bleeding edge than tests-passed and a bit more up-to-date than stable, i.e. again, it seems “sensible”. But in most cases it’s not a good idea.

  • “beta” is a term used in both Discourse version numbers and as a Discourse branch name. I’ve found this confuses some people.


“Beta” probably puts off some semi-computer-literate people like me – the usual meaning is “still testing for quality” rather than “still adding features”.

I guess I’m thinking mostly of the version names rather than the branch name. I had assumed I was on a “beta” branch based on the version names (I’m not) until checking now, so none of it put me off…


Yes. I think that it’s confusing (or I can see how it might be confusing) that you’re on tests-passed and the version shows up as “beta” but you can do an upgrade and get new code that is the same beta version that you are already on. And it’s weeks and hundreds of commit between beta releases.


I’ve made some edits to this guide to incorporate some of the discussion and material referenced above: Configure a supported tracking branch to get Discourse software updates