Creating a Separate Technical and Business Versioning System

Question

A common problem at my company is versioning. We follow a versioning system formatted very similar to semantic versioning (but not by definition). Our current versioning is not only used by development, but also by marketing/sales in their release notes, advertising, etc. Often times, there are conflicts as to what the versioning should be. What the development team defines as a major change (non-backwards compatible api change) is often not considered a "major" change by marketing. Other times, marketing will push to increment the major because their is a significant customer workflow change, but from a development perspective, the change is very insignificant (often times just an application code patch).

I am pushing heavily to separate our versioning into two distinct systems, a business versioning and a technical versioning system. This would allow both teams to define their own rules for versioning that best suites their needs. While the feedback in general is positive, some of the concerns are the confusion that this will cause, in our cross team communication and ticketing systems.

What are some of the complications of having two versioning systems? What are some of the benefits of a separation? What kind of impact will this have on the teams and the company as a whole?

Answer 1

It seems to me that your customers should be dictating the versioning. Both teams seem to be heading towards the same thing but only partially understanding the customer impact. For development, when they significantly re-architect components, there is risk because this could corrupt data or leave core features in a malfunctioning state - this should be reflected by a major version number change.

This doesn't mean much to marketing - everything looks the same, so why would the customer notice this change? No need to reflect this as a major change... unless you are a developer, in which case you risk a huge amount support interactions over those bugs.

Similarly marketing is looking at the user interface with the assumption that with a significant overhaul to the GUI, customers might get lost or hate the new user interface. This could lead to significant support interactions helping customer navigate the new UX, so should be reflected as a major version number change to the customer. There is a lot of risks there... Unless you are developer. Then this is purely cosmetic. Everything is still functioning the same on the back end.

So it seems you need to decide what it is that you feel version numbering is for.

• Are version numbers used to signal risk to customers?
• What source control system are you using
• Does Development even need version numbers at all or are commit IDs sufficient?
• Does Development plan features against version numbering for the purposes of setting deadlines?

Depending on the answers, it might be ideal to use a single version numbering system led by marketing - but marketing will need to do a better job of understanding the risks of under-the-hood changes. If this is needed as a designator for setting deadlines for change integrations, then two version numbering systems might be approperite:

Side note: git tags would be great for any version numbering scheme you have mentioned.

Answer 2

In my opinion the software version should not be updated if the documentation changes, while the software itself does not change.

I do not prefer to use different versioning for technical documentation and software as the docs are related to a certain software version. Different versioning will result in confusion.

In conclusion, one could use the same versioning, but if only the doc is updated one could add metadata, like 1.2.3-20171017. By using metadata one could still see that the doc belongs to version x of the software and one could also see that the doc has been updated.