Skip to content

RELEASE.md

Latest commit

 

History

History
192 lines (134 loc) · 4.17 KB

RELEASE.md

File metadata and controls

192 lines (134 loc) · 4.17 KB
Raw

Release Guide

This document describes how to release a new version of trend_classifier.

Prerequisites

Before releasing, ensure you have:

  • GitHub CLI installed and authenticated (gh auth status)
  • PyPI API token configured in GitHub secrets (PYPI_API_TOKEN)
  • Clean working directory (git status shows no changes)
  • All tests passing (make test)
  • On the main branch

Quick Release (Recommended)

One command handles the entire release process:

make release-patch   # 0.3.0 → 0.3.1 (bug fixes)
make release-minor   # 0.3.0 → 0.4.0 (new features)
make release-major   # 0.3.0 → 1.0.0 (breaking changes)

This automatically:

  1. ✅ Runs tests, linting, and security checks
  2. ✅ Bumps version in all files
  3. ✅ Updates CHANGELOG.md with git-cliff
  4. ✅ Commits changes with conventional commit message
  5. ✅ Creates git tag (v0.x.x)
  6. ✅ Pushes to GitHub (main branch + tags)
  7. ✅ Creates GitHub Release with release notes
  8. ✅ Triggers PyPI publish via GitHub Actions

Version Locations

The version is maintained in two files (updated automatically by bump-my-version):

File Field
pyproject.toml version = "X.X.X"
src/trend_classifier/__init__.py __version__ = "X.X.X"

Useful Commands

Command Purpose
make show-version Show current version
make preview-release-notes Preview changelog for current version
make changelog Regenerate full CHANGELOG.md
make version-patch Bump version only (no commit/tag/push)
make version-minor Bump minor version only
make version-major Bump major version only

Manual Release Steps

If automation fails, follow these steps:

1. Run Quality Checks

make lint
make type-check
make security
make test-cov

2. Bump Version

# Choose one:
uv run bump-my-version bump patch  # 0.3.0 → 0.3.1
uv run bump-my-version bump minor  # 0.3.0 → 0.4.0
uv run bump-my-version bump major  # 0.3.0 → 1.0.0

3. Update Changelog

uv run git-cliff -o CHANGELOG.md

4. Commit and Tag

VERSION=$(uv run bump-my-version show current_version)
git add -A
git commit -m "chore(release): bump version to $VERSION"
git tag "v$VERSION"

5. Push to GitHub

git push origin main --tags

6. Create GitHub Release

VERSION=$(uv run bump-my-version show current_version)
gh release create "v$VERSION" \
    --title "Release $VERSION" \
    --generate-notes \
    --latest

7. Verify PyPI Publication

The GitHub Actions workflow (.github/workflows/release.yml) automatically publishes to PyPI when a v* tag is pushed.

Check status at: https://github.com/izikeros/trend_classifier/actions

GitHub Actions Workflow

Trigger: Push tag matching v*

Steps:

  1. Checkout code
  2. Set up Python 3.12
  3. Install uv
  4. Build package (uv build)
  5. Publish to PyPI (trusted publishing)

File: .github/workflows/release.yml

Troubleshooting

"Working directory is not clean"

git status
git stash  # or commit/discard changes

"gh: command not found"

brew install gh
gh auth login

"Version already exists on PyPI"

You cannot republish the same version. Bump to a new version and try again.

"Tests failing"

Fix tests before releasing:

make test-cov

"GitHub release failed but tag pushed"

Create release manually:

gh release create "v0.3.1" --title "Release 0.3.1" --generate-notes

"PyPI publish failed"

  1. Check GitHub Actions logs
  2. Verify PYPI_API_TOKEN secret is set
  3. Manual publish as fallback:
make build
uv run twine upload dist/*

Versioning Strategy

This project follows Semantic Versioning:

  • MAJOR (1.0.0): Breaking API changes
  • MINOR (0.1.0): New features, backward compatible
  • PATCH (0.0.1): Bug fixes, backward compatible

Changelog Format

The changelog is generated by git-cliff using conventional commits:

  • feat: → 🚀 Features
  • fix: → 🐛 Bug Fixes
  • perf: → ⚡ Performance
  • break: → 💥 Breaking Changes

Configuration: cliff.toml