Skip to content

versioning.md

Latest commit

 

History

History
87 lines (63 loc) · 2.49 KB

versioning.md

File metadata and controls

87 lines (63 loc) · 2.49 KB

Versioning

Snapshot uses semantic versioning. The project started at 1.0.0; the current package version is managed through the single source below.

Single Source

The release version lives in pyproject.toml:

[project]
version = "1.1.0"

Runtime version values prefer pyproject.toml when running from a source tree and fall back to installed package metadata in packaged environments:

  • snapshot.__version__
  • AppConstants.APP_VERSION
  • FastAPI/OpenAPI metadata
  • GET /

This avoids manually changing the same version in multiple files.

Automated Bumps

Snapshot is configured for Python Semantic Release. It reads Conventional Commits and decides the next version:

Commit Bump
fix: correct MIME validation Patch, for example 1.0.0 -> 1.0.1
feat: add S3 storage Minor, for example 1.0.0 -> 1.1.0
feat!: change response schema Major, for example 1.0.0 -> 2.0.0

Preview the next version without changing files:

semantic-release --noop version --print

Create a release version, commit, and tag locally:

semantic-release version
git push --follow-tags

Pushing a tag such as v1.0.1 triggers the release workflow's tag publishing path and creates GHCR tags.

In normal project flow after v1.0.0 you do not need to run this locally. Push Conventional Commits to main; the Release GitHub Actions workflow runs the quality gate, creates the semantic release, and publishes the Docker image to:

ghcr.io/walkaisa/snapshot

The release workflow intentionally publishes Docker in the same run that creates the GitHub release. That avoids relying on a second workflow being triggered by a tag that was pushed by GITHUB_TOKEN.

First Release

For a clean first public release, create the new repository with main as the default branch. Then push the initial commit and tag exactly that commit:

git branch -M main
git remote add origin https://github.com/Walkaisa/snapshot.git
git add .
git commit -m "chore: initial release"
git push -u origin main
git tag v1.0.0
git push origin v1.0.0

This first manual tag creates the GitHub Release if it does not exist yet and publishes the initial Docker image. After that, let Semantic Release manage future version tags from commit messages.

Release Notes

Snapshot does not keep a repository CHANGELOG.md. GitHub Releases are the source for published release notes. Semantic Release derives those notes from Conventional Commits when it creates a release.