Skip to content
Tutorials Center
My learning

Topics

Lesson 17 of 38 ยท Building and Publishing

Versioning and Changelogs

Choose between semantic and calendar versioning, keep one source of truth for the version, derive it from Git tags, and write a useful changelog, with live code.

A version number is a promise to your users. "This is safe to upgrade to" or "this might break you" should be readable from the number alone. This lesson covers how to choose a scheme, where to store the number so that it never disagrees with itself, how to automate bumps, and how to write the changelog that explains each release.

Choosing a scheme

Semantic versioning (SemVer)

MAJOR.MINOR.PATCH, for example 2.4.1:

  • MAJOR: incompatible changes to the public API.
  • MINOR: new, backward-compatible functionality.
  • PATCH: backward-compatible bug fixes.

Users can then write ~=2.4 or >=2.4,<3 with confidence. Pre-1.0 versions (0.y.z) mean "anything may change", though many projects treat the minor as the breaking number. Python's PEP 440 permits all SemVer-shaped numbers, with pre-releases spelled 1.0.0rc1 rather than 1.0.0-rc.1.

Calendar versioning (CalVer)

YYYY.MM.PATCH (pip, pytz, black, certifi) or YY.MINOR. It says when, not how big, which suits tools where "how old is this?" matters (time zone data, certificates, formatters that change style yearly) and projects that release on a schedule.

Choosing

Situation Scheme
A library other code depends on SemVer
Data or tool released on a calendar CalVer
An application nobody imports Either; SemVer is fine

The most important rule is consistency, followed by documenting what counts as a breaking change. Deprecate before you remove: ship a warning in a minor release, remove in the next major.

Manipulating versions in code

You can classify and bump versions with packaging.version.Version. A bump helper is a handful of lines and shows the logic that release tools automate.

Python Semantic version bumps with packaging

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

One source of truth

The classic bug: pyproject.toml says 0.3.0, __init__.py says 0.2.9, and the Git tag says v0.3. Pick one place and derive the others.

Option 1: static in pyproject.toml. Simple and explicit. Read it at runtime with importlib.metadata.version("weather-cli"); never duplicate it in code.

TOML
[project]
name = "weather-cli"
version = "0.3.0"
Python
# weather_cli/__init__.py
from importlib.metadata import version, PackageNotFoundError
try:
    __version__ = version("weather-cli")
except PackageNotFoundError:
    __version__ = "0+unknown"

Option 2: a dynamic version read from a file. The version lives in __init__.py or a _version.py, and the backend reads it at build time:

TOML
[project]
dynamic = ["version"]

[tool.hatch.version]
path = "src/weather_cli/__init__.py"       # looks for __version__ = "..."
# setuptools:  [tool.setuptools.dynamic] version = {attr = "weather_cli.__version__"}
# flit:        reads __version__ automatically

Option 3: derived from Git tags. Tools such as hatch-vcs, setuptools-scm and uv-dynamic-versioning compute the version from the latest tag (v1.2.0) plus commits since then (1.2.1.dev3+g1a2b3c4). Releasing becomes git tag v1.3.0 && git push --tags. No file edits, no mismatches.

TOML
[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"

[project]
dynamic = ["version"]

[tool.hatch.version]
source = "vcs"
Python How a version is derived from Git describe output

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Local versions (+g1a2b3c4) are fine for development builds but PyPI rejects them, which is a useful safety net: you cannot upload an untagged build by accident.

Release workflow

flowchart LR
    A["Merge changes<br/>update changelog"] --> B["Choose next version<br/>(SemVer rules)"]
    B --> C["Tag: git tag v1.3.0"]
    C --> D["CI: build + test<br/>wheel and sdist"]
    D --> E["Publish to PyPI"]
    E --> F["GitHub release notes<br/>from changelog"]

Tagging is the trigger; everything after is automatic.

Keeping a changelog

A changelog answers "what changed and do I need to act?" It is for humans, not a dump of git log. The popular format, Keep a Changelog, groups entries by release and by type:

MARKDOWN
# Changelog

## [Unreleased]

## [1.3.0] - 2025-04-02
### Added
- `--units` option to choose metric or imperial output.
### Changed
- Requests are retried twice before failing.
### Deprecated
- `weather_cli.fmt.old_format()`; use `format_report()` instead. Removal in 2.0.
### Fixed
- Crash when the city name contains a slash (#41).
### Security
- Updated `requests` floor to 2.32 (CVE fix).

[1.3.0]: https://github.com/example/weather-cli/compare/v1.2.0...v1.3.0

Tips that make changelogs useful:

  • Write entries from the user's point of view. "Fix crash on slash in city names" beats "refactor parser".
  • Put a date on every release; keep an Unreleased section at the top.
  • Mark breaking changes loudly and say how to migrate.
  • Link each version to the diff; link issues and pull requests.
  • Tools help: towncrier assembles entries from small per-change files (avoiding merge conflicts), git-cliff and release-please generate from conventional commits.
Python Extracting the newest release notes from a changelog

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

This kind of extraction feeds the release notes of a GitHub or GitLab release automatically in CI, so the changelog stays the single source of truth.

PyPI never lets you re-upload a filename that existed, even after deleting it. If you publish a bad release, yank it (it stays installable by exact pin but is skipped by resolvers) and publish a new, higher version.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You remove a public function. Under semantic versioning, which part should change?

    Removing or changing public API in an incompatible way requires a MAJOR bump (after a deprecation period if possible).
  2. 2. What is the main advantage of deriving the version from Git tags?

    Tools like hatch-vcs and setuptools-scm compute the version at build time from the latest tag.
  3. 3. How should code read its own installed version?

    The installed metadata is authoritative and cannot drift from the built package.
  4. 4. You uploaded a broken 1.3.0. What is the right fix?

    PyPI filenames can never be reused. Yank the bad release and publish a new version.

Summary

  • SemVer (MAJOR.MINOR.PATCH) suits libraries; CalVer suits date-driven projects. Be consistent and document breaking changes.
  • Keep one source of truth for the version: static in pyproject.toml, dynamic from a file, or derived from Git tags.
  • Read the version at runtime with importlib.metadata.version().
  • Never reuse a version number; yank bad releases and publish a new one.
  • Keep a human-written changelog (Keep a Changelog format or towncrier) and reuse it for release notes.

Next: Publishing to PyPI