| What is Semantic Versioning? |
Semantic versioning reflects changes in software in a predictable manner
it helps in managing the dependencies of various software libraries
ensures that projects that depend on libraries aren''t unexpectedly broken by new versions
the format of semantic versioning is expressed as X.Y.Z.,
- X - a major version
- Y - a minor version
- Z - a patch version
|
| The Rules of Semantic Versioning |
| Version | Description |
|---|
| Major (X) |
increment the major version when incompatible API changes are made
indicates the new version may not be backwards compatible
|
| Minor (Y) |
increment the minor version when functionality is added in a backwards-compatible manner
this allows implementations to add features without disrupting existing usage
|
| Patch (Z) |
increment the patch version when backwards-compatible bug fixes are made
primarily for making fixes that do not affect the software's functionality.
|
additional labels for pre-release and build metadata
-
pre-release versions can be denoted by appending a hyphen and a series of dot-separated identifiers immediately following the patch version
3.0.0-alpha.1
-
Build metadata can be included by appending a plus sign and a series of dot-separated identifiers immediately following the patch or pre-release version
3.0.0+20130313144700
|
| Benefits of Using Semantic Versioning |
| Benefit | Description |
|---|
| predictability |
dependencies can be updated without inadvertently breaking the software
changes in major versions indicate breaking changes, minor versions indicate new features, and patches are just fixes.
|
| transparency |
version changes communicate the nature of changes in the software
builds trust and facilitates easier maintenance and upgrading of software
|
| streamlined dependency management |
dependency management tools can automatically manage versions based on the semantic versioning specifications
reduces the overhead of manual oversight in many development workflows
|
|
| Implementing Semantic Versioning |
| starting a new project |
when beginning a new project start with version 0.1.0
the initial development phase is typically a time when many changes might be made
the software is not yet stable
consider version 1.0.0 to be the initial release version
|
| moving to production |
once the software is stable and ready for production, increment to version 1.0.0
marks the public API's stability
lets users know the software is considered production-ready
|
| version rules |
increment the patch version for critical bug fixes and minor issues that do not affect the software's operation
when adding new features that do not break existing functionality, bump the minor version
make a major version increment when changes are breaking or remove previous functionalities
|
| communicating changes |
maintain a change log to accompany the versioned software
log should provide a clear history of the project
state what changes were made with each version increment
|
|