Suppose I’m developing a (javascript) library which is hosted on a public repo (e.g. github). My aim in terms of how version numbers are assigned and incremented is to follow the guidelines of semantic versioning.
Now, there’s a number of files in my project which compose the actual lib and a number of files that ‘support it’, the latter being docs, a test suite, etc. My perspective this far has been that version numbers should only apply to the actual lib – not the project as a whole – since the lib alone is ‘the unit’ that defines the public API.
However I’m not satisfied with this approach as, for example, a fix in the test suite constitutes an ‘improvement’ in my project, which will not be reflected in the version number (or the docs which contain a reference to it). On a more practical level, various tools, such as package managers, may (understandably) not play along with this strategy. For example, when trying to publish a change which is not reflected in the version number, npm publish fails with the suggestion “Bump the ‘version’ field set the –force flag, or npm unpublish”.
Am I doing it wrong?
My perspective this far has been that version numbers should only apply to the actual lib – not the project as a whole – since the lib alone is ‘the unit’ that defines the public API.
But to the World your final Product is something more: A combination of
- Code (the lib per se)
- Doc
- Test-sute
If you change anything in this triad you get new version of product which can’t (logically) share the old one’s ID.
If you prefer to strictly follow SV-rules and use only 3-octets, you can
- Use p.7 for all non-library changes
Patch version Z (x.y.Z | x > 0) MUST be incremented if only backwards compatible bug fixes are introduced
docs|tests changes may be considered as bug-fixes and they are backwards compatible. Thus, from version 1.1.0, docs changesets may increment it towards 1.1.9999, but not 1.2.0
- Operate with p.11 for non-core code changes
A build version MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch version or pre-release version.
and from 1.1.0, the version will be incremented towards 1.1.0+9999.