Breaking changes and the next major version
This page is for designers who must change something users depend on. A breaking change is one after which a user's site does not work, or looks different, unless they act.
Examples
| Breaking | Not breaking |
|---|---|
| Removing a template users override | Adding a template |
| Renaming a setting without reading the old name | Adding a setting with a default |
| Raising the minimum Exponential or PHP version | Supporting a newer version too |
| A redesign of the layout | A fix of a visual bug |
Step by step
- Avoid it if you can: keep the old way working (A deprecation policy).
- Group breaking changes into one release rather than spreading them.
- Choose the version deliberately: move a higher position (for example
1.xto2.0.0), so users with a constraint such as~1.0.24do not receive it by accident (Version constraints your users write). - Write an upgrade guide (
UPGRADE-2.0.md): every change, what the user must do, in order. - Keep the previous line in security-only maintenance for a stated time (A support policy).
- Announce before and at the release.
Related pages
- Choosing a version number
- Declaring compatibility
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.