NPM/semver versioning dilemma

npmVersionDilemma.md

NPM Versioning Dilemma

Background on my Node module

• I have an existing published Node module, flex-sdk, which basically serves as a downloader and wrapper for an external, non-JavaScript dependency: the Adobe/Apache Flex SDK.
• As such, the Node module's version number is based on the version of the Flex SDK which it wraps, e.g. flex-sdk@4.5.1 == Flex SDK 4.5.1
• I just discovered that I should also be bundling additional Flash API libraries (for compilation) with these various SDKs.

The Problem

• NPM versioning is based on Semantic Versioning (SemVer).
• NPM no longer allows you to unpublish-and-republish an exact version number, and rightfully so for security's sake.
• SemVer versioning includes the idea of pre-release version numbers via a following - notation, e.g. 1.0.0-0.
  • These version notations do gain version precedence, e.g. 1.0.0-0 < 1.0.0-1.
  • However, they specifically represent pre-release software, which, IMHO, is not semantically correct in this case.
• SemVer versioning includes the idea of build number metadata via a following + notation, e.g. 1.0.0+100.
  • However, SemVer build numbers do not gain any version precedence over their build-number-less equivalent, e.g. 1.0.0+100 has the same precedence as 1.0.0:

  Build metadata SHOULD be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence.

How to Proceed

• Update the existing module with "build numbers" anyway... hopefully people can work it out on their own.
• Recreate the existing module (plus the new sub-dependencies) with a new name but:
  • following the same versioning scheme;
  • use a bastardized pre-release versioning scheme instead (via a following - notation, e.g. 1.0.0-0) to correctly manage version precedence [but with "incorrect" versions as they are not pre-release]; or
  • NON-OPTION: use a completely unrelated versioning scheme (e.g. 0.0.1 == 4.5.1) and provide a mapping in the README
• Create a completely new and separate module, flash-api-lib, [with a peerDependency on flex-sdk] that install the sub-dependencies into its peer flex-sdk directory.
  • TROUBLE: If this approach is used, any updates to flex-sdk will delete the installed flash-api-lib files from within it, so a user would have to re-install flash-api-lib after updating flex-sdk. Doable but pretty lame.
• NON-OPTION: Do nothing and make users manually install the new sub-dependencies.