Improving our engineering best practices with semantic versioning

Product versioning - that is, assigning numbers to each release to easily differentiate them - is a common and convenient practice. There can be more to versioning than just assigning each release a number though. Semantic versioning defines a system for version numbers that helps developers understand what is in a release and how much effort it might take them to upgrade from an earlier version.

At Tiny, we have long been proponents of product versioning. However, we have not been particularly strict about what versions mean. Recently we made the decision to change this, and are now moving towards strictly following the semantic versioning specification.

But what is semantic versioning, and what do our changes mean for you?

What is semantic versioning?

Many developers are familiar with what is often called “dependency hell”. In particular, one problem developers can hit is when a dependency updates in a way that is not backward-compatible and therefore breaks their project. Depending on how reliant the project is on the changed features and how big the change is, this kind of problem can be a quick fix or a massive headache. 

The goal of semantic versioning is to give version numbers meaning so that developers can predict what kind of work will be involved in updating a dependency to a newer version. To do this, semantic versioning defines a format for version numbers and a set of rules around how version numbers are incremented depending on what was changed in a release. 

The format used for semantic versioning is MAJOR.MINOR.PATCH. The first release of a product is given the version 1.0.0, and each update after that increments the relevant numbers depending on what kind of release it is. The kinds of releases are:

• Patch: Backward-compatible bug fixes (e.g., 1.0.1)
• Minor: Backward-compatible new features (e.g., 1.1.0)
• Major: Any kind of changes that are not backward-compatible (e.g., 2.0.0)

You may have noticed that this not only specifies numbers for backward compatible and incompatible changes, but also differentiates between bug fixes and new features. The idea is that backward-compatible bug fixes in a dependency should require the least effort for developers to integrate, if any. If developers want to use new backward-compatible features, they might need to do some setup or integration, but minor releases should not require work to use out-of-the-box. In comparison, any kind of breaking changes, no matter whether it is a bug fix or a new feature, could require a large amount of work for integrating developers.

By describing what is in a version, semantic versioning allows developers to predict how much work they might need to do to upgrade a dependency. Some package managers also allow developers to pin a dependency to a “range” of versions, which allows the dependency to automatically upgrade within that range. Combined with semantic versioning, if developers pin dependencies to patch or minor ranges, their project can update without the risk of introducing breaking changes.

For example, if you use NPM as the package manager for a project, you can pin dependencies using NPM’s version range syntax.

If you would like to learn more about semantic versioning, we recommend reading the official specification.

How semantic versioning of TinyMCE helps you

Although Tiny has used product versioning for a long time now, our versioning hasn’t always been descriptive. For example, TinyMCE Enterprise 5.0.14, although only a patch release, contained PowerPaste 5.1.0. Although we did document this in the release notes, it is not obvious from just the TinyMCE version that it contains a minor version of one of the Enterprise components. This had the potential to cause problems for customers who upgraded TinyMCE without knowing about the changes to PowerPaste.

To prevent such problems, from the release of TinyMCE 5.1, TinyMCE releases will adhere to the following versioning rules:

• TinyMCE will follow the rules of semantic versioning
• All premium plugins will also follow the rules of semantic versioning
• Enterprise releases, since they use TinyMCE’s versioning, will only contain premium plugin releases of the same kind or lesser

The last point is perhaps the most important for Enterprise customers to understand. To explain it in more detail:

• A patch release of Enterprise (e.g., 5.0.1) can only contain patch releases of TinyMCE and any premium plugins
• A minor release of Enterprise (e.g., 5.1.0) will contain a minor release of TinyMCE and only patch or minor releases of any premium plugins
• A major release of Enterprise (e.g., 6.0.0) will contain a major release of TinyMCE and patch, minor or major releases of any premium plugins

The other change will be to our release schedule. Releases that only contain bug fixes require less post-development work from the various other teams in Tiny, so we will be able to release them quickly. However, it may slow down major and minor releases for premium plugins, since they can only go out in major or minor versions of TinyMCE. While that may slightly decrease the rate at which we release new features, we believe the increase in stability and predictability for our customers is worth it.

Of course, in a process change like this, there are always road bumps during the transition. We are planning to release a major update to one of our premium plugins soon, which will unfortunately break our new semantic versioning rules, as it was prepared before the switch. We have tried to minimize the potential impact by pushing it out to a minor TinyMCE release though, and by ensuring it is as backward-compatible as possible. We also intend to ensure this exception - and any future exceptions -  is well documented in the release notes.

How semantic versioning helps Tiny

The other great thing about our shift to strict semantic versioning is that it also helps the various teams and departments at Tiny to be on the same page about releases. The Quality Assurance team know what kind of work to expect in each Enterprise release, and can more easily plan their testing accordingly. The teams who look after our website and cloud services are able to predict what kinds of updates they’ll need to do for a release. And the Support, Marketing, and Sales teams can know, at a glance, the impact of each release from their perspectives.

This switch has also been part of a larger shift towards better development practices and processes within Engineering at Tiny. For example, we have also implemented Git Flow-like processes within the TinyMCE team, which, incidentally, has made it easier to implement semantic versioning.

What’s next?

Tiny is committed to building excellent things in excellent ways for our customers. Switching to semantic versioning is just one step in our ongoing effort to improve both our internal practices and the ways in which we deliver TinyMCE. Keep an eye out for news about our next steps! For example, you can also find out more about our new CDN infrastructure for Tiny Cloud.

If you would like to hear about updates, connect with us on Twitter, and feel free to contact us for more information.

And if you haven’t tried out TinyMCE yet, get a free API Key to try it now. You’ll even get a free trial of our premium plugins!