Semantic versioning - gregswindle/eslint-plugin-crc GitHub Wiki
Semantic Versioning (semver)
How this project usesThis product follows the Semantic Versioning 2.0 specification for communicating changes by type to both humans and software agents.
1. Bump principles
:information_source: Bumps are
major
,minor
, orpatch
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:
- BREAKING CHANGE: The public API introduces something that could throw exceptions in previous versions.
- feat: A new feature.
- fix: A bug fix.
- revert: The release goes back to a previous commit.
:white_check_mark: 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.
:white_check_mark: This project follows the angular convention for Git commit messages.
3. Definitions of "change"
patch
for defect fixes, new non-functional features, and refactoring changes
3.1. For example, if I add CI/CD stuff to the project or fix a defect, each addition or fix includes a patch
bump.
minor
for new features and reversions
3.2. 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
major
for breaking changes
3.3. If a change at any point during a development iteration results in backwards incompatibility, the major
version will be incremented.
1.0.0
release exception
3.4. The 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
:information_source: 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.
:neckbeard: 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.