Semantic Versioning

Overview Semantic Versioning, or SemVer, is the industry standard for managing software releases. It moves versioning away from arbitrary numbers toward a system where every digit conveys a specific meaning about the underlying code changes. This predictability is the backbone of modern dependency management, ensuring that developers can update libraries without fear of breaking their applications. Prerequisites To get the most out of this guide, you should understand the concept of a Public API and have experience managing third-party dependencies. Familiarity with Python Packages and basic terminal usage will help when applying these concepts in real-world environments. Key Libraries & Tools * **SemVer 2.0.0**: The specific specification governing these versioning rules. * Poetry: A modern Python dependency manager that automates SemVer increments and lockfile management. Code Walkthrough The structure of a semantic version follows the `X.Y.Z` format. Each segment represents a distinct level of change. Patch (Z): Bug Fixes Increment the patch version for backward-compatible bug fixes. ```bash From 1.5.6 to 1.5.7 Fixes an edge case where a function might crash. ``` Minor (Y): New Features Increment the minor version when adding functionality in a backward-compatible manner. When you bump the minor version, you must reset the patch to zero. ```bash From 1.5.3 to 1.6.0 Added a new endpoint to the API. ``` Major (X): Breaking Changes Increment the major version for incompatible API changes. This signals to users that they must update their own code to remain compatible. Both minor and patch versions reset to zero. ```bash From 1.6.0 to 2.0.0 Renamed core access points or removed deprecated features. ``` Syntax Notes SemVer uses non-negative integers. When comparing versions, the precedence is determined from left to right. This means `3.0.0` is always higher than `2.9.9`. For pre-release builds, append a hyphen and an identifier, such as `1.0.0-beta`. Interestingly, a pre-release version has lower precedence than the stable version it precedes. Tips & Gotchas Always start new projects at `0.1.0`. The `0.x.y` range is the Wild West; anything can change at any time. Move to `1.0.0` only when your software is production-ready. Avoid "identifier bloat" by limiting pre-release tags to two segments—nobody wants to debug `1.0.0-alpha.beta.sigma.delta`. Finally, remember that while tools like Poetry help, the developer ultimately decides if a change is truly "breaking."