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?

  • Isn't using a different scheme for each a viable alternative option to disambiguate business and software versions ?
    – Tensibai
    Oct 17, 2017 at 15:31
  • Correct. That is what I'm referring to. The push back however is that there will be confusion between teams when referring to different versions in cross team communications such as documentation, feature requests, etc.
    – Preston Martin
    Oct 17, 2017 at 15:38
  • There's no reason, let the marketing have a fancy prefix for their taste and keep the actual version after, for Soft 2.3.5, business version 2k17-2.3.5 should do, business could then upgrade to 2k18-2.3.6 for the case you were talking about without impacting the semver of the software.
    – Tensibai
    Oct 17, 2017 at 16:04
  • Your software isn't a library or API of some sort, right, but a GUI application? Oct 20, 2017 at 6:34
  • @XiongChiamiov Our products are an assortment of web and desktop applications. Some of them also utilize or include a library/API that would be versioned as well.
    – Preston Martin
    Oct 20, 2017 at 16:54

2 Answers 2


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.


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.

  • 1
    Updating the doc should be a patch increase in the software IMHO
    – Tensibai
    Oct 17, 2017 at 16:03

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.