Propose we add documentation on version info and number our system to match. There's a note that this applies to Mattermost 3.8 or later, so propose it's okay to merge this ahead of 3.8 release.

After these docs are done, we should create tickets to link About Mattermost dialog and platform version command to these docs.

0/5 on below, open to feedback.

Version Information

Note:

The following applies to Mattermost server version 3.8.0 and later.

You can find the version information for your Mattermost server and database using either the user interface or the commandline tool.

Finding version information using commandline tool

To find version information for your Mattermost server and database using the commandline tool use the command:

platform version

Which will output version information in the following format:

Server Version: [SERVER_VERSION][-SPECIAL_RELEASE_INDICATOR]
Build Number: [BUILD_NUMBER]
Build Date: [BUILD_DATE]
Build Hash: [BUILD_HASH]
Build Accepts License Key: [BUILD_ACCEPTS_LICENSE_KEY]
Database Schema Version: [DATABASE_SCHEMA_VERSION]
Database Type: [DATABASE_TYPE]

See documentation below for description of values.

Finding version information using web interface

To find version information for your Mattermost server and database using the web interface go to the Main Menu and select About Mattermost. The information is included:

Mattermost Team Edition - if [BUILD_ACCEPTS_LICENSE_KEY] is false Mattermost Enterprise Edition - if [BUILD_ACCEPTS_LICENSE_KEY] is true

Server Version: [SERVER_VERSION][-SPECIAL_RELEASE_INDICATOR] ([BUILD_NUMBER]) Database: [DATABASE_TYPE] (Mattermost schema version: [DATABASE_SCHEMA_VERSION])

Build Date: [BUILD_DATE] Build Hash: [BUILD_HASH]

??? // Why do we have both Build Hash and EE Build Hash in the footer?

Build and version fields

The following describe fields used to indicate version and build information.

Server Version

Mattermost server version numbers releases based on the following format:

[Version Number].[Major Build Number].[Minor Build Number]

Version Number: Indicates a major system release (e.g. 1.x.x, 2.x.x)
- Incrementing this number represents a major change to the codebase and potentially incompatibility with the previous major version release.
Major Build Number: Indicates significant new functionality, (e.g. 0.5.x, 0.6.x, 0.7.x)
- This number is incremented with each monthly release on the 16th of the month, and represents significant code changes from the previous major build release. May require update to database schema.
Minor Build Number: Indicates a bug fix or security release (e.g. 1.2.5, 1.2.6)
- This number is incremented for high priority bug fixes or security releases and does not typically contain significant code changes. Except for extremely rare circumstances, will not require update to database schema.

Special Release Indicator

Within the server version, special release indicator text after the version number indicates a special release, for example: 3.6.0-rc1, 3.6.1-temp, etc.

-rc[RELEASE_CANDIDATE_NUMBER] - This tag is used to indicate build is a candidate for an official release. E.g. 3.6.0-rc1. -temp - This tag is used to indicate the build is a temporary variant created, typically for a specific customer to test custom changes that will be later integrated back into an official release.

Build Number

// What is this?

Build Date

The time and date at which build was created based on UTC-0 timezone.

Build Hash

// Explain what this is used for and how to use it.

Build Accepts License Key

true - Indicates the build accepts a license key to enable Enterprise Edition features. This indicates the build is for the commercial Mattermost Enterprise Edition, which can be used for free with the same features of the open source Mattermost Team Edition, with the added benefit of being able to upgrade.

false - Indicates the build does not accept a license key, and cannot enable Enterprise Edition features. This indicates the build is for the open source Mattermost Team Edition. To accept a license key, the Mattermost server requires upgrade to Mattermost Enterprise Edition (link).

Database Schema Version

This indicates the schema version of the Mattermost database, with numbering similar to the Mattermost server version. The database schema version is set by the Mattermost server on install and on upgrades when the Mattermost database schema is updated. If no updates to the Mattermost server are made, the schema version is not updated. A list of database changes from version to version is indicated in the Mattermost changelog (link).

No database connected or database unreachable - If the database has yet to be connected, display this text for the value from the commandline tool.

Database Type

This field indicates either "MySQL" or "PostgreSQL" as the database type used. By default, Mattermost uses the full text search in either database, and search results will vary slightly depending on which is used. See documentation for details (link).

MySQL - indicates MySQL database is used PostgreSQL - indicates PostgreSQL database is used No database connected or database unreachable - indicates a database has not yet been set up

This is not so much about docs, but more about release and version management. The problem is not in the documentation, the documentation is very helpful. What is confusing, is that the team uses almost identical numbers for different things.

Based on the most recent release of January 31st:

version: 3.6.0 Although the actual version is 3.6.2 (according to the release date and notes), for some reason the version number reported by mattermost is 3.6.0 in the logs, suggesting that this mattermost version should be upgraded to 3.6.2. I strongly advise to use semantic versioning for the version number (see semver.org )

build: 3.6.2 Although buildnumbers are usually linear counters, the mattermost team chose to have build numbers which almost look like version numbers. A build number is just a number which increases with each (internal) build. In this case, I would expect the build number to be 87235 or something like that, unrelated to the version number to prevent confusion.

Database Schema version: When the database structure does not change between mattermost software versions, the database version should stay the same. I would advocate to have a separate database versioning scheme, also using semantic versioning. This numbering should be distinct and separate from the mattermost software version.

The build hash should indeed be explained, particularly how an end user should use this hash to validate that the downloaded version is unmodified. PGP Signature may be more appropriate, particularly for enterprise releases.

A more sensible version number for this release would be: Version 3.6.2 build 23425 database schema version 2.0.1

@it33: not sure if your questions are still unanswered. (If they ever were.) Hope you don't mind if I ponder over them.

??? // Why do we have both Build Hash and EE Build Hash in the footer?

Assuming:

you have different feature sets for EE and non-EE and
the EE features live in their own (private) git repository/branch/....

To know which version your client is running it does not suffice to know the non-EE version since the changes introduced in the EE version could change behavior of non-EE features. (Being able to tell which cool shiny extras the client has doesn't help either if you are unable to identify the non-EE version they were applied to.) Hence, you need to publish them both.

Build Number // What is this?

As @realrolfje already said:

A build number is just a number which increases with each (internal) build.

If your company also uses some sort of CI solution (maybe bamboo?) this number can reference a build done by this CI. (In case of random build failures for the same build hash it is helpful to have an identifier for the build one is talking about.)

Build Hash // Explain what this is used for and how to use it.

According to the current Makefile the build hash is:

BUILD_HASH = $(shell git rev-parse HEAD)

i.e. it is the git commit used for the build. You can use it to interrelate a build number to a git commit.

This is not so much about docs, but more about release and version management. The problem is not in the documentation, the documentation is very helpful.

Agreed.

What is confusing, is that the team uses almost identical numbers for different things.

I disagree. As long each number has a name, which is written right next to it, it doesn't matter if those numbers look similar. I argue that the latter is currently not true. E.g. in this screenshot: About Mattermost the word "dev" (in parentheses, right behind the version) has no name. After reading this issue, I'd call it "build number". (Then again, the following does sound strange to me: "Its build number is dev.")

The build hash should indeed be explained, particularly how an end user should use this hash to validate that the downloaded version is unmodified.

I disagree. The version information is for debugging purpose when reporting and issue.

(Someone signed the binary download somewhere as well. It would be nice if one could reproduce the build as well.)

As a conclusion my suggestion would be:

Do not change the version scheme of Mattermost. You just:
- changed the repository name to mattermost-server
- introduced another repository as dependency (mattermost-webapp)
- announced the deprecation of an API
That's enough structural changes for the next months or so.
Do reduce the amount of manual interventions into naming a release. (I.e. nobody should have to write the current version into a file.)
Do use the name of the current git tag as Mattermost version (similar to how you determine the build hash).
Consider to change e.g. Version 1.2.3 (4567) to Version 1.2.3 (build #4567). Tell people how they should call those numbers

Thanks @SmartHoneybee, thanks @realrolfje, sorry for the late reply. This was meant more for the core committers, though definitely appreciate your chiming in,

My issue is that I'm not aware of documentation that explains how Mattermost's different components--server, mobile app, desktop app, (webapp?) are supposed to be labeled in terms of version number and build number.

My sense is if we could get a couple of people spending 30-60 minutes thinking about this we could have a draft of documentation ready to go, explaining what we should do, how it should be displayed (e.g. what should the mobile app screen look like to communicate which mobile app version and which server version is being used when reporting a bug), and what should be the process in future.

Just curious, which countries are you in?

We're preparing to organize some global meetups for our open source community, perhaps we can triangulate a city near you. It could be interesting to try and knock this out over drinks or snacks,

documentation that explains how Mattermost's different components are supposed to be labeled

Release Numbering looks very similar to the "Server Version" subsection of your first suggestion/post. What confuses me is that the documentation talks about "Mattermost". (What does that refer to in this context? Is it: code/company/...) Anyway, the described version number does look similar to the earlier suggested Semantic Versioning and seems to be consistent across the components. (At least, that is my impression.) Claiming to adhere to semantic versioning might introduce the need to check, prior to each release, that one indeed does. On the other hand it could reduce the documentation overhead. (Overly simplified: specify the meaning of "Mattermost"; add a "uses semantic versioning [link]"-sentence; done.)

(webapp?)

The webapp seems to be a result of a recent repository split (platform to mattermost-server and mattermost-webapp).

which countries are you in?

Thanks for asking, but I like to pretend that I'm anonymous. (Even though ... drinks and snacks sound tempting.) You could try to "hijack" some go/JavaScript meetings - but you probably already preparing something like that.

By the way, the CI really does use build #XXX to identify the XXX-th build of a project.

We do document how we name our versions here: https://handbook.mattermost.com/operations/research-and-development/product/release-process/release-overview. However, this is an interesting suggestion that could also apply to development as well as Support.

In terms of development, @jwilander, can you confirm whether this does affect any of the teams or whether it's documented somewhere?

In terms of support, @svelle, we have a page about how to log a support ticket: https://handbook.mattermost.com/operations/customer-success/customer-support, but I'm wondering if we should add details about how to find the version number?

In terms of documentation we do have instructions here: https://docs.mattermost.com/configure/configuration-settings.html?highlight=version.

@justinegeffen I could see this living in the KB or the docs whatever you prefer but yeah I feel like some simple steps to get the version info (and also showing the difference between version of mobile, desktop, webapp and server) would be useful.

For development purposes we use commits to track what code is in which build (hashes at the bottom of the about modal). We do use the release version number to track the database schema and to version our Go code too. Not aware of that being documented anywhere.

mattermost / docs

Document version info for server and database #979