Semantic versioning

How this project uses Semantic Versioning (semver)

This product follows the Semantic Versioning 2.0 specification for communicating changes by type to both humans and software agents.

1. Bump principles

ℹ️ Bumps are major, minor, or patch version increments.

1.1. Bumps are not related to releases

This project increments its product's semver without regard to a release.

1.2. One change, one bump

Every change intended for the master branch must have an associated semver increment.

:person_with_pouting_face: Are we bumping too promiscuously?

Nah. If we can agree that release versions - aka "marketing" versions - and semver serve separate purposes, then it makes sense that semver strictly reflect software product changes.

Remember, semver is not only for humans, but also software. Semver gets us closer to automated dependency vulnerability and incompatibility detection and resolution.

2. Rules and guidelines

2.1. Tag every change

No matter what: each patch, minor, and major change has an associated tag in Git.

2.2. Log every feature, fix, reversion, and breaking change

Prepend and publish these types of changes in a running CHANGELOG:

1. BREAKING CHANGE: The public API introduces something that could throw exceptions in previous versions.
2. feat: A new feature.
3. fix: A bug fix.
4. revert: The release goes back to a previous commit.

✅ This project automatically updates its CHANGELOG with conventional-changelog.

2.3. Enforce strict commit message formats

In order to automatically generate meaningful CHANGELOGs, contributors must adhere to the a commit message format.

✅ This project follows the angular convention for Git commit messages.

3. Definitions of "change"

3.1. patch for defect fixes, new non-functional features, and refactoring changes

For example, if I add CI/CD stuff to the project or fix a defect, each addition or fix includes a patch bump.

3.2. minor for new features and reversions

Likewise, once I've completed a milestone, I bump the minor version. For example, if an MVP release consists of four milestones, then there will be four minor version increments. In other words, if we start at

1.0.0

and add four features before the republishing on npm, the next public version of the product will be

1.4.0

3.3. major for breaking changes

If a change at any point during a development iteration results in backwards incompatibility, the major version will be incremented.

3.4. The 1.0.0 release exception

The only exception to this approach will be the initial launch of the product, which will be versioned at 1.0.0. Anything before or after the 1.0.0 release will resume following the aforementioned principles, rules, and guidelines.

4. Release versions vs. semantic versions

ℹ️ Release version defined

A release version usually designates new stuff that might be attractive to potential consumers. Release versions should therefore be simple to remember using Chronological Versioning (Werd 2017), Enumerated Versioning (version 1, version 2...version n), or Subjective Versioning (OS Olympus Mons).

This product does not make a distinction between release versions and semantic versions, since its target users/consumers are

• Software developers, architects, and designers
• Build, test, and integration engineers

If this product were targeting a different consumer base, I would use a simpler "release version" in addition to, but not instead of, semver.

And yeah, you can find opinionated debates about the merits and demerits of semver. If you have a better idea, publish it! Meanwhile, semver is a step in the right direction.