Understanding how to manage your package versions is essential for ensuring that users and other developers can rely on your code without unexpected surprises. Semantic versioning, often referred to as semver, is a widely adopted system that uses a three-part numbering scheme: MAJOR.MINOR.PATCH. Each segment of the version number conveys specific information about the nature of changes introduced in the release.

The MAJOR version is incremented when you make changes that break backward compatibility, meaning users may need to modify their code to work with the new version. The MINOR version is incremented when you add new features in a backward-compatible manner, so existing functionality continues to work as before. The PATCH version is reserved for backward-compatible bug fixes—small changes that do not affect features or public APIs.

Following semantic versioning helps users and contributors quickly understand the impact of updating to a new release. It also guides you as a package maintainer in communicating the significance of your changes.

# Suppose your package currently has version 1.2.3 in pyproject.toml.
# You have just added a new feature without breaking existing APIs.

[project]
name = "my_package"
version = "1.3.0"
# The MINOR version was incremented from 2 to 3, and PATCH reset to 0.

# If you introduce a breaking change, update the MAJOR version:
# version = "2.0.0"

# For a backward-compatible bug fix:
# version = "1.3.1"