Version Management Guide¶

This guide explains how to manage versions and create releases for S5 Slidefactory.

Overview¶

S5 Slidefactory uses Semantic Versioning (SemVer) for version numbers:

MAJOR.MINOR.PATCH (e.g., 1.0.1)
MAJOR: Breaking changes or major feature releases (1.0.0 → 2.0.0)
MINOR: New features, backwards-compatible (1.0.0 → 1.1.0)
PATCH: Bug fixes, backwards-compatible (1.0.0 → 1.0.1)

Two-Step Release Process¶

Step 1: Bump Version¶

Use the /bump-version Claude command or run the script directly:

# Preview changes (recommended first step)
python scripts/bump_version.py patch --dry-run

# Apply version bump
python scripts/bump_version.py patch   # For bug fixes
python scripts/bump_version.py minor   # For new features
python scripts/bump_version.py major   # For breaking changes

This will: - Update version in pyproject.toml - Update version in s5_branding/__init__.py - Create new version entry in CHANGELOG.md

After bumping: 1. Edit CHANGELOG.md to document what changed in this version 2. Review all changes with git diff

Step 2: Create Release¶

Use the /release-version Claude command or run the script directly:

./scripts/create_release.sh

This interactive script will: 1. Show current version and files to commit 2. Create git commit: chore: release version X.Y.Z 3. Create git tag: vX.Y.Z 4. Optionally push to remote 5. Optionally create GitHub release

Version Locations¶

S5 Client Version (This Package)¶

The S5 client version is managed by the version bump tools:

pyproject.toml - Package version
s5_branding/__init__.py - Module version
CHANGELOG.md - Version history

Core Dependency Version (Separate)¶

The slidefactory-core dependency has its own version and must be updated separately:

Dockerfile - ARG CORE_VERSION=x.y.z
.github/workflows/preview.yml - Build arg
.github/workflows/production.yml - Build arg

To update core dependency: Use /update-core command

Manual Release Process¶

If you prefer manual control or need to troubleshoot:

1. Bump Version Manually¶

# Edit pyproject.toml
sed -i 's/version = "1.0.0"/version = "1.0.1"/' pyproject.toml

# Edit s5_branding/__init__.py
sed -i 's/__version__ = "1.0.0"/__version__ = "1.0.1"/' s5_branding/__init__.py

# Edit CHANGELOG.md (add new version entry)
# ... manual editing ...

2. Create Release Manually¶

# Stage files
git add pyproject.toml s5_branding/__init__.py CHANGELOG.md
git add .claude/commands/*.md scripts/*.py scripts/*.sh

# Commit
git commit -m "chore: release version 1.0.1"

# Create tag
git tag -a v1.0.1 -m "Release v1.0.1"

# Push
git push && git push --tags

3. Create GitHub Release¶

Using gh CLI:¶

VERSION="1.0.1"
CHANGELOG=$(sed -n "/## \[$VERSION\]/,/## \[/p" CHANGELOG.md | sed '1d;$d')

gh release create "v$VERSION" \
    --title "v$VERSION" \
    --notes "$CHANGELOG" \
    --latest

Manually on GitHub:¶

Visit: https://github.com/cgast/s5-slidefactory/releases/new

Choose tag: v1.0.1
Title: v1.0.1
Copy release notes from CHANGELOG.md
Click "Publish release"

Changelog Format¶

We follow Keep a Changelog format:

## [Unreleased]

## [1.0.1] - 2025-11-24

### Added
- New features or capabilities

### Changed
- Changes to existing functionality

### Fixed
- Bug fixes

### Removed
- Removed features or capabilities

### Security
- Security-related changes

Examples¶

Patch Release (Bug Fix)¶

# Bump version
python scripts/bump_version.py patch

# Edit CHANGELOG.md
# Add: "Fixed authentication token expiration issue"

# Create release
./scripts/create_release.sh

Minor Release (New Feature)¶

# Bump version
python scripts/bump_version.py minor

# Edit CHANGELOG.md
# Add: "Added support for custom templates"

# Create release
./scripts/create_release.sh

Major Release (Breaking Change)¶

# Bump version
python scripts/bump_version.py major

# Edit CHANGELOG.md
# Add: "Redesigned API with breaking changes"

# Create release
./scripts/create_release.sh

Branch Strategy¶

preview branch: Development and staging
All feature development and testing happens here
Automatic deployment to preview environment
Create commits, test changes, and iterate here
main branch: Production releases
Merge from preview when ready for production release
Automatic deployment to production environment
Version releases (commits, tags) are created on main after merging from preview

Workflow: 1. Develop and test features on preview branch 2. When ready for release: merge preview → main 3. On main: bump version, create release commit and tag 4. Push to trigger production deployment

Version vs Release¶

Version bump changes version numbers in code files. This can be done anytime during development.

Release creates a git tag and GitHub release. This should only be done when ready to deploy.

You can bump versions multiple times (1.0.1 → 1.0.2 → 1.0.3) during development and only create releases when ready.

Troubleshooting¶

Tag Already Exists¶

# Delete local tag
git tag -d v1.0.1

# Delete remote tag (careful!)
git push --delete origin v1.0.1

# Recreate
git tag -a v1.0.1 -m "Release v1.0.1"
git push --tags

Wrong Version Bumped¶

# Undo last commit (keeps changes)
git reset --soft HEAD~1

# Fix version numbers
python scripts/bump_version.py <correct-type>

# Commit again
git add .
git commit -m "chore: release version X.Y.Z"

Push Failed (Behind Remote)¶

# Fetch and rebase
git fetch origin
git rebase origin/preview  # or origin/main

# Push again
git push && git push --tags

Tools Reference¶

Scripts¶

scripts/bump_version.py - Automated version bumping
scripts/create_release.sh - Automated release creation

Claude Commands¶

/bump-version - Interactive version bump workflow
/release-version - Interactive release creation workflow
/update-core - Update core dependency version

Files Modified¶

pyproject.toml - Package metadata
s5_branding/__init__.py - Module version
CHANGELOG.md - Version history
.claude/commands/bump-version.md - Version bump documentation
.claude/commands/release-version.md - Release documentation

Best Practices¶

Always use --dry-run first to preview version bumps
Document changes in CHANGELOG.md before releasing
Test locally before creating releases
Review git diff before committing
Use semantic versioning correctly:
Patch: Bug fixes only
Minor: New features, backwards-compatible
Major: Breaking changes
Keep CHANGELOG.md updated throughout development
Create releases only when ready to deploy