How we deal with *Breaking Changes* - Proposal and Community Feedback Thread

[chriddyp]

👋 Hello Dash Community --

It's been almost a year and a half since we launched Dash and we're getting to a point where we feel like we need to make some breaking changes to move the product forward.

At Plotly, we take backwards compatibility pretty seriously. Over the last 5 years of developing plotly.js (the graphing library behind dcc.Graph), we've published over 100 releases, all without introducing a single breaking change.

When we make a breaking change in Dash, we're asking everyone our community to take time out of their day to read a migration guide and upgrade their code. In this issue, I'd like to share with you how we plan on easing this burden as much as possible. As always, your feedback is welcome and appreciated.

---

Prioritizing Backwards Compatibility

We will always try to keep breaking changes to a minimum by making new features backwards compatible.

Communications

Breaking changes should not take you by surprise. You should have time to prepare for them and you should be notified when they are in the immediate horizon.
Everyone has different methods for notifications (email, github, rss, etc). We also don't want these notifications to get lost in the sea of Dash updates.

Here's a proposal for how we'll try to notify you when we're going to make a breaking change.

1. A "Breaking Changes Notification Issue" in this repository. We will lock down this issue and we'll only comment in the issue when we see a breaking change in the horizon. You can subscribe to this issue (See the GitHub documentation on subscribing) to receive an email notification when there is a new comment.
2. A "Breaking Changes" email list for Dash developers and Dash component authors. This will be separate from the Dash Club email list. Dash Club will continue to contain general Dash news, this email list will only email you if a breaking change is on the horizon.
3. We'll mention this in the Dash Club newsletter as well.

If you weren't aware of these notification channels, then we'll try to notify you as you browse the documentation and forum:

1. A banner in the Dash User Guide (https://dash.plot.ly) notifying you that the next version is coming. This will be up for at least 2 weeks before the change is published.
2. A pinned post in the Dash Community Forum (https://community.plot.ly/c/dash). Also pinned for at least 2 weeks.

Also, you should be aware that a breaking change was made via our versioning scheme (see below).

Versioning, Semver, and Changelogs

1. We will communicate breaking changes in our version numbers by incrementing the Major version number (Versions are MAJOR.MINOR.PATCH. In the version 5.14.8, 5 is the "major" number). This is the semver way.

   This means that if we go from version 0.5.12 to version 1.0.0, we've made some change that could cause your code to break.
   Unlike other software, our versioning scheme does not indicate if we've "made a big feature": switching from 1.2.5 to 2.0.0 only means that we've made a breaking change, it doesn't necessarily mean that we've introduced new functionality.

2. Semver is only effective if users are aware of:

   • Their version number
   • The latest package's version number
   • The concept of semver (semver is by no means the standard way to version packages)
   • A link to upgrade guides

   We will work raise version awareness through our official Dash installation instructions (https://dash.plot.ly/installation) by:

   • Displaying the latest our version numbers of the main packages
   • Encouraging version awareness by specifying specific versions (i.e. rather than pip install dash, we will always say pip install dash==0.29.0)
   • Notifying our users that we use semver
   • Providing links to each package's CHANGELOG
   • Telling users how to check the version of the package that they have installed

   

   For our Dash Deployment Server customers, we'll always lock down the versions in the sample applications.

3. Each GitHub project contains a CHANGELOG.md file, formatted in the [keep a changelog](https://keepachangelog.com/en/1.0.0/) style.

   • These files are linked to from the installation instructions

Compatibility Between Packages
In the Dash ecosystem, certain packages depend on each other:

• dash and dash-renderer communicate to each other
• Every component library depends on dash-renderer to render the components
• Component libraries depend on dash for their base Component class

So, if we make a breaking change in one library, it could require compatibility fixes in other libraries. We could imagine that this would be difficult to keep track of.

To make this easier, we'll keep the major versions of the major package in sync with each other:

• Major packages include: dash, dash-renderer, dash-core-components, dash-html-components and the dash-component-boilerplate project.
• So, all packages in a certain series will be guaranteed to be compatible with each other. So, if you upgrade to dash==1.0.0, you will need to upgrade the rest of your packages to something in the "1.x.x" series, ideally the latest version within that series.
• This will be automatically enforced when you install or upgrade the component libraries. For example, in the "1.x.x" series, dash-core-components and dash-html-components will have install_requires=['dash >= 1.0.0, < 2.0.0', 'dash-renderer > 1.0.0, < 2.0.0']. If you upgrade dash-core-components or dash-html-components, dash and dash-renderer will automatically get upgraded.
• We will continue to test old series and we will incorporate bug and security fixes into old series. We will not incorporate new features into old series as this could slow down our development too much.
• Note that a major version bump does not mean that each particular package has a breaking change, it only means that at least one of the packages has a breaking change. We increment all of the version numbers purely to guarantee that the packages will be compatible with each other.
• Not all dash packages will adhere to this versioning scheme. Only the packages that we listed above. For example, dash-table will have a version number that is independent of the other packages as we intend to make several breaking changes while we work through its alpha status.

Upgrade Guides and Prelease Versions

• We will author a GitHub issue with a full list of the breaking changes and instructions to upgrade
• This issue and a prerelease will be published at least 2 weeks before we publish the breaking change to allow you to prepare and/or provide feedback
• Our CHANGELOG.md file will be updated with these same instructions and prerelease instructions
• This GitHub issue will be linked to from the notification channels above

Two weeks may seem like a short amount of time to prepare. However, note that we aren't removing old versions of the packages from the package repositories. If you have your versions pinned (as you should) and installing the packages on a per-project basis (e.g. with virtualenv), then you will not be impacted immediately by the release of the new versions.

Documentation

• Our user guide will always contain the most up-to-date versions in the installation instructions
• The user guide and the examples contained within will always be compatible and up-to-date with the latest versions
• We may not keep documentation pertaining to the old versions available on our website.
• We will keep our documentation open source (https://github.com/plotly/dash-docs) so that you can run the docs locally and check out old versions if necessary

Community Forum Examples
The community forum may contain many examples that are no longer compatible with the latest versions of the package. These threads come up when users search for particular examples in Google and many users learn dash through examples in the community forum rather than reading through the user guide.

So, we will attempt to update old community threads with either an updated example or a note that this thread is no longer relevant.

For example, here are two notes we made in the popular "Display tables in Dash" topic when our release of the new data-table made many comments in the thread obsolete:
At the top of the thread:

At the bottom of the thread:

Incorporating Feedback on the Release

Before we release our official "Upgrade Guide", we will publish an issue in this repository with a "Proposed Breaking Changes".

This will happen at least 2 weeks before we commit to the breaking changes via the official "Upgrade Guide".

This will allow the community to provide us feedback on the proposed set of breaking changes.

We will communicate this issue by:

• Creating the issue in GitHub. If you are watching the repo, you will receive a notification for it.
• Creating a post in the Dash Community Forum
• Mentioning this in the Dash Club newsletter.

We will not communicate this via our other "breaking changes" notification channels as we want to keep those notifications to an absolute minimum.

Grouping Together Breaking Changes to Reduce the Frequency of Breaking Changes

To reduce the frequency at which we publish breaking changes, we will make a best effort to combine several breaking changes into a single release. That way, you only need to go through the maintenance process a single time. This will also ease the communication burden as these changes will be widely shared.

---

Thanks for reading and for your understanding. As always, your feedback is welcome and appreciated ❤️