Deprecation policy
Last updated
Was this helpful?
Last updated
Was this helpful?
This document outlines the process for announcing deprecated features to the community. The guiding principle is with guaranteed long-term stability, where admins or users should never run into anything unexpected while using Mattermost.
A deprecated feature is considered to be one that breaks backwards compatibility with previous versions.
Examples include:
1) Removing an API endpoint, or one of its parameters.
APIv3 endpoints on January 16, 2018.
“permanent” parameter of the DELETE /teams/{team_id} APIv4 endpoint in Mattermost v5.0.0.
2) Removing a config.json setting
System Console settings in Files > Images in Mattermost v4.0.0.
3) Removing an end user setting or functionality.
Font setting in Account Settings > Display in Mattermost v4.0.0.
When the decision to deprecate a feature or function is made, the product manager responsible for the feature carries out the following actions:
Adds the scheduled deprecation to the with a note of what it's been replaced with.
Prepares a forum post describing the reasons for deprecating the feature, providing an opportunity for the community to share feedback. See a .
Creates a JIRA ticket for removing the feature, including a prefix “Deprecation:” and a fix version matching the removal target date.
Moreover, the acting release manager takes the following actions:
The removal target date should always be the date of the next major release, such as v4.0.0. If the date is not known, you can reference the next major version rather than the actual release date.
However, there should always be at least two months from the time the deprecation is announced to its removal. This number is chosen to match our security backport release policy.
See the table below for examples:
3.9.0
3.10.0
4.0.0
3.10.0
3.10.0
5.0.0
Exceptions for the removal target date may be made if it impacts security or the performance of Mattermost. In such cases, the target date for removing the feature may be made sooner.
On the other hand, if removing a feature is deemed significant, such as the removal of APIv3 endpoints, the target date for removing the feature may be extended to a later release.
, adds a list of deprecated features to the compatibility section of the and . The changelog should include deprecations scheduled for upcoming releases.
, sends the list of deprecated features to the marketing manager, who includes this information in the release announcement.
, ensures the is up to date.