StarPunk/docs/standards/version-implementation-guide.md

Version Implementation Guide

Quick Reference

This guide shows exactly where and how version information is stored in StarPunk.

See Also: versioning-strategy.md for complete strategy documentation.

Version Storage Locations

1. Primary Source: starpunk/__init__.py

Status: ✅ Already implemented

Location: /home/phil/Projects/starpunk/starpunk/__init__.py

Content:

# Package version (Semantic Versioning 2.0.0)
# See docs/standards/versioning-strategy.md for details
__version__ = "0.1.0"
__version_info__ = (0, 1, 0)

Usage:

from starpunk import __version__, __version_info__

print(f"StarPunk version {__version__}")
print(f"Version info: {__version_info__}")  # (0, 1, 0)

Format:

• __version__: String in PEP 440 format (e.g., "1.0.0", "1.0.0a1", "1.0.0rc1")
• __version_info__: Tuple of integers (major, minor, patch) for programmatic comparison

---

2. README.md

Status: ✅ Already implemented

Location: /home/phil/Projects/starpunk/README.md

Content: Shows current version at the top of the file:

# StarPunk

A minimal, self-hosted IndieWeb CMS for publishing notes with RSS syndication.

**Current Version**: 0.1.0 (development)

## Versioning

StarPunk follows [Semantic Versioning 2.0.0](https://semver.org/):
- Version format: `MAJOR.MINOR.PATCH`
- Current: `0.1.0` (pre-release development)
- First stable release will be `1.0.0`

Update when: Version changes (manually)

---

3. CHANGELOG.md

Status: ✅ Created

Location: /home/phil/Projects/starpunk/CHANGELOG.md

Format: Based on Keep a Changelog

Structure:

# Changelog

## [Unreleased]

### Added
- Features being developed

## [1.0.0] - 2024-11-18

### Added
- New features

### Changed
- Changes to existing features

### Fixed
- Bug fixes

### Security
- Security patches

Update when: Every change (add to [Unreleased]), then move to versioned section on release

---

4. Git Tags

Status: ⏳ To be created when releasing

Format: vMAJOR.MINOR.PATCH[-PRERELEASE]

Examples:

v0.1.0          # Development version
v0.2.0          # Next development version
v1.0.0-alpha.1  # Alpha pre-release
v1.0.0-beta.1   # Beta pre-release
v1.0.0-rc.1     # Release candidate
v1.0.0          # Stable release

How to Create:

# Annotated tag (recommended)
git tag -a v0.1.0 -m "Development version 0.1.0: Phase 1.1 complete

- Core utilities implemented
- Slug generation
- File operations
- Content hashing

See CHANGELOG.md for full details."

# Push tag
git push origin v0.1.0

Current Tags: None yet (will create when Phase 1.1 is complete)

---

5. pyproject.toml (Optional, Future)

Status: ⚠️ Not currently used

Location: /home/phil/Projects/starpunk/pyproject.toml (if created)

Content (if we create this file):

[project]
name = "starpunk"
version = "0.1.0"
description = "Minimal IndieWeb CMS"
authors = [
    {name = "Your Name", email = "your@email.com"}
]
dependencies = [
    "flask>=3.0.0",
    "python-markdown>=3.5.0",
    "feedgen>=1.0.0",
    "httpx>=0.25.0",
]

[project.urls]
Homepage = "https://github.com/YOUR_USERNAME/starpunk"
Repository = "https://github.com/YOUR_USERNAME/starpunk"
Changelog = "https://github.com/YOUR_USERNAME/starpunk/blob/main/CHANGELOG.md"

Decision: Not needed for V1 (keeping it simple)

---

How to Update Version

Step-by-Step Process

When you're ready to release a new version:

1. Decide on Version Number

Use the decision tree from versioning-strategy.md:

• Breaking changes? → Increment MAJOR (e.g., 1.0.0 → 2.0.0)
• New features? → Increment MINOR (e.g., 1.0.0 → 1.1.0)
• Bug fixes only? → Increment PATCH (e.g., 1.0.0 → 1.0.1)

During 0.x development:

• Phase complete? → Increment MINOR (e.g., 0.1.0 → 0.2.0)
• Bug fix? → Increment PATCH (e.g., 0.1.0 → 0.1.1)

2. Update starpunk/__init__.py

# Change version strings
__version__ = "0.2.0"  # New version
__version_info__ = (0, 2, 0)  # New version tuple

3. Update CHANGELOG.md

Move [Unreleased] items to new version section:

## [Unreleased]

### Added

### Changed

### Fixed

## [0.2.0] - 2024-11-19

### Added
- Data models implementation
- Database schema
- Note class with validation

### Changed
- Improved error handling in utilities

[Unreleased]: https://github.com/YOUR_USERNAME/starpunk/compare/v0.2.0...HEAD
[0.2.0]: https://github.com/YOUR_USERNAME/starpunk/compare/v0.1.0...v0.2.0
[0.1.0]: https://github.com/YOUR_USERNAME/starpunk/releases/tag/v0.1.0

4. Update README.md

Change current version:

**Current Version**: 0.2.0 (development)

5. Commit Changes

git add starpunk/__init__.py CHANGELOG.md README.md
git commit -m "Bump version to 0.2.0"

6. Create Git Tag

git tag -a v0.2.0 -m "Development version 0.2.0: Phase 1.2 complete

- Data models implementation
- Database schema defined
- Note class with full validation
- Session and token models

See CHANGELOG.md for full details."

7. Push to Repository

git push origin main
git push origin v0.2.0

8. Create GitHub Release (Optional)

If using GitHub:

1. Go to repository → Releases
2. Click "Draft a new release"
3. Choose tag: v0.2.0
4. Release title: Version 0.2.0
5. Description: Copy from CHANGELOG.md
6. Publish release

---

How to Check Version

From Python Code

# Method 1: Import from package
from starpunk import __version__
print(f"Version: {__version__}")

# Method 2: Use version_info for comparisons
from starpunk import __version_info__
if __version_info__ >= (1, 0, 0):
    print("Stable release")
else:
    print("Development version")

From Command Line

# Method 1: Python one-liner
python -c "from starpunk import __version__; print(__version__)"

# Method 2: Check Git tags
git tag -l

# Method 3: Check current HEAD tag
git describe --tags --abbrev=0

# Method 4: Show all version info
git describe --tags

From Web Interface (Future)

When implemented, will show in:

• Footer of all pages
• /api/info endpoint
• Admin dashboard

---

Version Comparison Examples

Using __version_info__

from starpunk import __version_info__

# Check minimum version
def require_version(major, minor, patch):
    return __version_info__ >= (major, minor, patch)

# Examples
if require_version(1, 0, 0):
    print("Running stable version")

if require_version(0, 2, 0):
    print("Has data models")

Parsing __version__ String

from starpunk import __version__
from packaging.version import Version

current = Version(__version__)
required = Version("1.0.0")

if current >= required:
    print("Version requirement met")

---

Release Checklist

Use this checklist when releasing a new version:

Pre-Release

• All tests pass: pytest
• Code formatted: black starpunk/ tests/
• Code linted: flake8 starpunk/ tests/
• Documentation updated
• All features working
• Manual testing completed

Version Bump

• Decide version number (MAJOR.MINOR.PATCH)
• Update starpunk/__init__.py → __version__
• Update starpunk/__init__.py → __version_info__
• Update CHANGELOG.md with changes and date
• Update README.md with current version
• Review changes: git diff

Commit and Tag

• Stage files: git add starpunk/__init__.py CHANGELOG.md README.md
• Commit: git commit -m "Bump version to X.Y.Z"
• Create annotated tag: git tag -a vX.Y.Z -m "Release X.Y.Z: [description]"
• Push commits: git push origin main
• Push tag: git push origin vX.Y.Z

Post-Release

• Verify tag exists: git tag -l
• Create GitHub release (if applicable)
• Test installation from tag
• Announce release (if applicable)
• Create [Unreleased] section in CHANGELOG.md for next development

---

Common Scenarios

Scenario 1: Completing a Development Phase

Situation: Phase 1.2 is complete (data models implemented)

Action:

1. Version: 0.1.0 → 0.2.0 (increment MINOR during 0.x)
2. Update __init__.py: __version__ = "0.2.0", __version_info__ = (0, 2, 0)
3. Update CHANGELOG: Add [0.2.0] section with date
4. Commit: "Bump version to 0.2.0"
5. Tag: v0.2.0
6. Push

Scenario 2: Fixing a Bug

Situation: Found bug in slug generation, fixed it

Action:

1. Version: 0.2.0 → 0.2.1 (increment PATCH)
2. Update __init__.py: __version__ = "0.2.1", __version_info__ = (0, 2, 1)
3. Update CHANGELOG: Add [0.2.1] section with bug fix
4. Commit: "Bump version to 0.2.1"
5. Tag: v0.2.1
6. Push

Scenario 3: First Stable Release

Situation: All V1 features complete, ready for production

Action:

1. Version: 0.9.0 → 1.0.0 (first stable release!)
2. Update __init__.py: __version__ = "1.0.0", __version_info__ = (1, 0, 0)
3. Update CHANGELOG: Comprehensive [1.0.0] section
4. Update README: Change "0.x.0 (development)" to "1.0.0 (stable)"
5. Commit: "Bump version to 1.0.0 - First stable release"
6. Tag: v1.0.0 with detailed release notes
7. Push
8. Create GitHub release with announcement

Scenario 4: Adding New Feature (Post-1.0)

Situation: Added tags feature in version 1.0.0, want to release it

Action:

1. Version: 1.0.0 → 1.1.0 (increment MINOR for new feature)
2. Update __init__.py: __version__ = "1.1.0", __version_info__ = (1, 1, 0)
3. Update CHANGELOG: Add [1.1.0] section with "Added: Tags support"
4. Commit and tag
5. Push

Scenario 5: Breaking Change (Post-1.0)

Situation: Changed Micropub API response format (breaking change)

Action:

1. Version: 1.5.0 → 2.0.0 (increment MAJOR for breaking change)
2. Update __init__.py: __version__ = "2.0.0", __version_info__ = (2, 0, 0)
3. Update CHANGELOG: Clear "Breaking Changes" section
4. Create upgrade guide: docs/upgrade/1.x-to-2.0.md
5. Commit and tag
6. Push
7. Prominently announce breaking changes

---

Troubleshooting

Version Mismatch

Problem: __version__ and __version_info__ don't match

Solution: They must always match:

# Correct
__version__ = "1.2.3"
__version_info__ = (1, 2, 3)

# Wrong
__version__ = "1.2.3"
__version_info__ = (1, 2, 0)  # Mismatch!

Forgot to Update CHANGELOG

Problem: Released version without updating CHANGELOG

Solution:

1. Update CHANGELOG now
2. Commit: "Update CHANGELOG for version X.Y.Z"
3. Don't change version number or tag
4. Consider creating patch release with corrected changelog

Wrong Version Number

Problem: Tagged v1.1.0 but should have been v2.0.0

Solution:

# Delete local tag
git tag -d v1.1.0

# Delete remote tag
git push origin :refs/tags/v1.1.0

# Create correct tag
git tag -a v2.0.0 -m "Release 2.0.0"
git push origin v2.0.0

Warning: Only do this immediately after release, before anyone uses the tag!

Git Tag vs Python Version Mismatch

Problem: Git tag says v1.0.0 but __version__ says "0.9.0"

Solution: These must always match:

1. Check Git tag: git describe --tags
2. Check Python version: python -c "from starpunk import __version__; print(__version__)"
3. They should match (ignoring v prefix)
4. If mismatch, fix __init__.py and create new tag

---

Pre-Release Versions

Alpha Releases

When: Early development, unstable, missing features

Format:

• Git tag: v1.0.0-alpha.1
• Python __version__: "1.0.0a1" (PEP 440 format)
• __version_info__: (1, 0, 0, "alpha", 1) (extended tuple)

Example:

__version__ = "1.0.0a1"
__version_info__ = (1, 0, 0)  # Simplified, or extended: (1, 0, 0, "alpha", 1)

Beta Releases

When: Feature complete, testing phase

Format:

• Git tag: v1.0.0-beta.1
• Python __version__: "1.0.0b1"
• __version_info__: (1, 0, 0)

Release Candidates

When: Final testing before stable release

Format:

• Git tag: v1.0.0-rc.1
• Python __version__: "1.0.0rc1"
• __version_info__: (1, 0, 0)

Note: For V1, we may skip pre-releases entirely and go straight to 1.0.0 if 0.x testing is sufficient.

---

Integration with Other Systems

Flask Application

# In Flask app
from starpunk import __version__

@app.route('/api/info')
def api_info():
    return {
        "name": "StarPunk",
        "version": __version__,
        "micropub_endpoint": "/api/micropub"
    }

CLI Tool (Future)

import click
from starpunk import __version__

@click.group()
@click.version_option(version=__version__, prog_name="StarPunk")
def cli():
    """StarPunk CMS"""
    pass

User-Agent String

from starpunk import __version__

USER_AGENT = f"StarPunk/{__version__} (https://github.com/YOUR_USERNAME/starpunk)"

# Use in HTTP requests
headers = {"User-Agent": USER_AGENT}

---

References

• Versioning Strategy (complete spec)
• ADR-008: Versioning Strategy
• Semantic Versioning 2.0.0
• PEP 440 - Version Identification
• Keep a Changelog

---

Document Version: 1.0 Last Updated: 2024-11-18 Status: Active