Software package versioning confusion

Question

I am working in embedded software domain and my primary work area is development of firmware for various MCUs.

I follow the folder structure as mentioned below for any firmware project to release the source code and docs as complete bundle (.zip archive) for customer use.

XYZ-project-2.0.zip |-> docs/ |-> XYZ-project-software-design-desciption-rev1.1.pdf |-> XYZ-project-software-user-guide-rev1.3.pdf |-> src/ |-> XYZ-project/ |-> src/ |-> test.c |-> inc/ |-> test.h Source code contains doxygen commenting. and it contains version number 2.0 (same as zip file). Customer always refer to this version for any discussion.

So, there are two main things that can be changed independently. One is source code and other is documents.

i increment the version number of XYZ-project-2.0.zip to XYZ-project-2.1.zip when

• If source code is changed (i also update the version number in doxygen comments from 2.0 to 2.1)
• Or Any of document version is changed.

The problem:

• Every time update any document, I change version number of that document (from XYZ-project-software-user-guide-rev1.3.pdf to XYZ-project-software-user-guide-rev1.4.pdf) and update zip file version number (from XYZ-project-2.0.zip to XYZ-project-2.1.zip). but, i also need to update version number inside source code to kept it same (doxygen version comment from 2.0 to 2.1).

So, My Question is,

• Is there any industry standard to co-relate software version and document version. And how should i version final zip file ?
• I still doubt what version tag i should add to any document. doc-Rev1.0.pdf? doc-v1.0.pdf? doc-Rev-A.pdf? Is there any standard ?

Thanks.

Answer 1

You have a package, and some parts inside the package (code & doc). Each part of the package can have a version number on its own, and the package itself another one. So lets call these three numbers

• code version number (maybe somewhere inside the code)
• doc version number (maybe somewhere inside the docs)
• package version number

When you change one of the parts, the package gets its version number increased, but not vice versa. To combine this with the requirement of referring to the package version number inside the documentation generated by doxygen, you need to put the package version number

• in one (and only one) place
• outside the code and doc parts
• somewhere, in machine-readable form, where your zipping script (the script which puts the version number into the zip file name) as well as doxygen can find it.

I hope you get the idea - you should try to create a single source of truth (so avoid to maintain the same number in two places like in the package name and the docs). And you should avoid cyclic dependencies - since the top level package depends on the parts, avoid to have a direct dependency from the parts to the package name. Instead, let them all depend on the separate source.

For example, a simple text file containing the package version number will do it, somewhere at the top of the hierarchy. Maybe you will find this former SO post helpful how to include such a file into doxygen. Moreover, it will probably be a good idea, whenever you refer to a version number inside the doxygen doc, make clear if it is the code version number or the package version number which is meant.

The exact format of version and revision numbers is up to you, Dan Pichelman already mentioned Semantic versioning, which is a sensible approach to pick the numbers, but not the only possible or only correct one.

Answer 2

Personally, I would track documentation revisions separately from the project:

• Document_v1_0_rev_A.pdf
• Document_v1_0_rev_B.pdf

Changing the documentation does not change the code, so changing the version number of the software itself seems unreasonable.

If I have the 2.0 zip file and you send me the 2.1 file, I will assume something changed that I need to be aware of. I might schedule a series of acceptance tests, or spend a few hours reading the "what's changed" documentation, etc.

If you upgraded the version number just because you fixed a typo in the documentation, I will be very annoyed with you.

See also Semantic Versioning - specific definitions for each of the 3 or 4 fields typically found in a version string.