MarketingVersion

From APIDesign

There is a difference between MarketingVersion and engineering approach to versioning, like Semantic versioning. Hear why:

Marketing Version

MarketingVersion is the one shown to end users and is associated with the whole product. It is a single label to help users understand and express what they are working with. Examples: Windows 10, Windows 11, Mac OS Sierra, Ubuntu 22.04, Ubuntu Jammy Jelly, Java 2, Java 11, etc.

There is no logic in marketing versioning. It is purely driven by marketing and other human centric needs. Even using date based YYYY-MM-DD-dev versioning is good enough.

Engineering Version

Engineering versions serve other purpose: they allow code to verify if the versions of other components are good enough to work with. Usually a form of semantic versioning is used for that. Often the system uses RangeDependencies to express intervals of compatibility.

Engineering versions are associated with components - not the whole product. There is usually way more such component versions inside of a single (marketed) product.

The engineering versions shall be incremented according to rules of compatibility to signal compatible as well as incompatible changes. That implies:

• the engineering version must be different than the marketing version
• there are many different engineering versions across the product as each component evolves differently and needs different versioning

Summary

There is a difference between MarketingVersion and engineering version. Keep that in mind and make sure you disassociate these two categories as soon as possible. The last thing a responsible API designer wants is to explain to marketing department what semantic versioning is - especially when trying to explain why changing the versioning from 1.9 to Jemmy Jelly or Java 9 is a breaking change from the perspective of code and BackwardCompatibility!