32 KiB
StarPunk Versioning Strategy
Overview
StarPunk uses Semantic Versioning 2.0.0 (SemVer) with Python ecosystem compliance (PEP 440) for version numbering. This strategy provides clear, predictable version numbers that communicate the nature of changes to users and developers.
Current Version: 0.1.0 (pre-release/development)
Version Format: MAJOR.MINOR.PATCH (e.g., 1.0.0)
Rationale
Semantic Versioning was chosen because:
- Industry Standard: Widely used in Python ecosystem (Flask, Django, etc.)
- Clear Communication: Version number immediately conveys type of changes
- Dependency Management: Works seamlessly with pip, uv, and Python packaging
- Simple and Predictable: Easy for indie developers to understand and apply
- IndieWeb Aligned: Transparent versioning supports independent, sustainable software
Version Number Format
Structure
MAJOR.MINOR.PATCH[-PRERELEASE][+BUILDMETADATA]
Examples:
0.1.0 - Development version
1.0.0 - First stable release
1.1.0 - Minor feature addition
1.1.1 - Bug fix
2.0.0 - Breaking change
1.0.0-alpha.1 - Alpha pre-release
1.0.0-beta.2 - Beta pre-release
1.0.0-rc.1 - Release candidate
Component Definitions
MAJOR - Increment when making incompatible changes:
- Breaking API changes (e.g., removing endpoints, changing response formats)
- Database schema changes requiring migration
- Configuration file format changes requiring user intervention
- Major architectural rewrites
- Removal of deprecated features
MINOR - Increment when adding functionality in a backward-compatible manner:
- New features (e.g., adding tags, categories)
- New API endpoints
- Non-breaking enhancements to existing features
- Addition of optional configuration parameters
- Performance improvements (significant)
PATCH - Increment for backward-compatible bug fixes:
- Bug fixes
- Security patches
- Documentation corrections
- Minor performance improvements
- Dependency updates (without feature changes)
PRE-RELEASE (optional) - Alpha, beta, and release candidate versions:
alpha.N- Early development, unstable, missing featuresbeta.N- Feature complete, testing and stabilizationrc.N- Release candidate, final testing before stable release
BUILD METADATA (optional, rarely used) - Build information:
- Not used for version precedence
- Example:
1.0.0+20241118.abc123
Version Lifecycle
Development Phase (Current: 0.x.y)
Status: Pre-1.0, anything may change at any time
- Version format:
0.MINOR.PATCH - MINOR increments for new features (Phase 1.1, 1.2, etc.)
- PATCH increments for bug fixes
- Public API should not be considered stable
- Breaking changes allowed without major version increment
Examples:
0.1.0 - Phase 1.1: Core utilities
0.2.0 - Phase 1.2: Data models
0.3.0 - Phase 1.3: Web routes
0.3.1 - Bug fix in web routes
0.4.0 - Phase 2.1: Micropub endpoint
1.0.0 - First stable release (V1 complete)
Pre-Release Versions
Alpha - Early development, experimental features:
1.0.0-alpha.1 - First alpha
1.0.0-alpha.2 - Second alpha
Beta - Feature complete, testing phase:
1.0.0-beta.1 - First beta
1.0.0-beta.2 - Second beta (bug fixes)
Release Candidate - Final testing before stable:
1.0.0-rc.1 - First release candidate
1.0.0-rc.2 - Second RC (critical fixes only)
Usage: Pre-releases are optional. For StarPunk V1, we may skip directly to 1.0.0 if development version (0.x.y) is sufficiently tested.
Stable Releases
First Stable Release: 1.0.0
- Indicates production-ready software
- All V1 features implemented and tested
- Public API is stable and documented
- Breaking changes require MAJOR version increment
Maintenance Releases: 1.0.x
- Bug fixes only
- Security patches
- Documentation updates
- No new features
- No breaking changes
Feature Releases: 1.x.0
- New backward-compatible features
- Enhancements to existing features
- Non-breaking API additions
- Optional new configuration parameters
Major Releases: x.0.0
- Breaking changes
- Major new features requiring incompatible changes
- Database schema changes
- Configuration format changes
Version Increment Decision Tree
┌─────────────────────────────────────────┐
│ Does the change break existing usage? │
│ (API, config, database schema) │
└─────────┬───────────────────────────────┘
│
┌─────┴─────┐
│ YES │
└─────┬─────┘
│
▼
┌───────────────┐
│ Increment │
│ MAJOR │
└───────────────┘
┌─────┴─────┐
│ NO │
└─────┬─────┘
│
▼
┌─────────────────────────────────────────┐
│ Does the change add new functionality? │
└─────────┬───────────────────────────────┘
│
┌─────┴─────┐
│ YES │
└─────┬─────┘
│
▼
┌───────────────┐
│ Increment │
│ MINOR │
└───────────────┘
┌─────┴─────┐
│ NO │
└─────┬─────┘
│
▼
┌─────────────────────────────────────────┐
│ Is this a bug fix, security patch, │
│ or documentation update? │
└─────────┬───────────────────────────────┘
│
┌─────┴─────┐
│ YES │
└─────┬─────┘
│
▼
┌───────────────┐
│ Increment │
│ PATCH │
└───────────────┘
Practical Examples
Scenario 1: Adding Tags Feature (Backward Compatible)
Change: Add optional tags to notes, new API endpoint /api/tags
Impact:
- Database: Add
tagstable (migration script provided) - API: Add new
/api/tagsendpoint (doesn't break existing endpoints) - Config: Add optional
ENABLE_TAGSsetting (defaults to false)
Version: 1.0.0 → 1.1.0 (MINOR increment)
Rationale: New feature, backward compatible, existing functionality unchanged
Scenario 2: Fixing RSS Feed Date Format Bug
Change: Fix RFC-822 date formatting in RSS feed
Impact:
- Bug fix only
- No API changes
- No configuration changes
- No breaking changes
Version: 1.1.0 → 1.1.1 (PATCH increment)
Rationale: Bug fix, backward compatible
Scenario 3: Changing Micropub Response Format
Change: Change Micropub endpoint response from 201 Created with Location header to JSON body with url field
Impact:
- Breaks existing Micropub clients
- API contract changed
- Incompatible with previous version
Version: 1.1.1 → 2.0.0 (MAJOR increment)
Rationale: Breaking API change requires major version
Scenario 4: Performance Optimization
Change: Optimize database queries for note listing
Impact:
- No API changes
- No configuration changes
- Faster response times
- No breaking changes
Version: 1.1.1 → 1.1.2 (PATCH increment)
Rationale: Internal improvement, no user-facing changes
Version Scope
Application Version
What: The overall StarPunk software version
Where Stored:
starpunk/__init__.py-__version__variablepyproject.toml-versionfield- Git tag -
vMAJOR.MINOR.PATCH
What It Covers:
- All StarPunk code
- API endpoints
- Web interface
- File storage format
- Configuration format
Example:
# starpunk/__init__.py
__version__ = "1.0.0"
API Version (Future Consideration)
When Needed: If we need to support multiple API versions simultaneously (V2+)
Format: URL-based versioning (e.g., /api/v1/notes, /api/v2/notes)
Relationship to Application Version:
- API v1 introduced in StarPunk 1.0.0
- API v2 might be introduced in StarPunk 2.0.0
- Both can coexist (e.g., StarPunk 2.5.0 supports both API v1 and v2)
V1 Decision: Not needed. Simple versioning via application version is sufficient.
Database Schema Version
What: Version of database schema structure
When Needed: If database migrations are required (V2+)
Format: Integer sequence (1, 2, 3, ...)
Storage: schema_version table or SQLite PRAGMA user_version
Relationship to Application Version:
- Schema version increments independently
- Application version specifies compatible schema versions
- Migration scripts bridge schema versions
V1 Decision: Not needed. Database schema is simple and stable. If migrations are needed in V2+, we'll add this.
Example (if implemented):
-- Store schema version
PRAGMA user_version = 1;
-- Migration script 001-to-002.sql increments to 2
PRAGMA user_version = 2;
Configuration Version
What: Version of configuration file format
When Needed: If .env or config format changes incompatibly
V1 Decision: Not needed. Configuration is simple and backward compatible.
V2+ Consideration: If config format changes:
- Add
CONFIG_VERSION=1to.env - Migration tool or clear upgrade documentation
- Version mismatch warning in application
Documentation Version
Strategy: Documentation is versioned with the code
Implementation:
- Docs stored in Git alongside code
- Git tags include documentation
- README shows current version
- Changelog documents changes
Multiple Versions: Not maintained. Latest documentation is for latest version.
Historical Docs: Available via Git tags (e.g., git checkout v1.0.0 shows docs for that version)
Git Workflow
Tag Naming Convention
Format: vMAJOR.MINOR.PATCH[-PRERELEASE]
Examples:
v0.1.0 Development version
v0.2.0 Development version with new features
v1.0.0-alpha.1 First alpha of 1.0
v1.0.0-beta.1 First beta of 1.0
v1.0.0-rc.1 Release candidate
v1.0.0 Stable release
v1.0.1 Bug fix release
v1.1.0 Feature release
v2.0.0 Major release
Prefix: Use v prefix for Git tags (common convention, distinguishes from other tags)
Tag Type
Use Annotated Tags (not lightweight tags)
Why:
- Contains tagger name, email, date
- Can include release notes
- Treated as full objects in Git
- Can be signed with GPG
Command:
git tag -a v1.0.0 -m "Release 1.0.0: First stable release"
Branch Strategy
Main Branch: main
- Always contains stable code
- Tagged for releases
- Protected (no direct commits)
Development Branch: develop (optional, V2+)
- Integration branch for features
- Not needed for single developer in V1
Release Branches: release/vX.Y.Z (optional, for testing)
- Created when preparing release
- Final testing and bug fixes
- Merged to main when ready
- Tagged on main branch
Feature Branches: feature/feature-name
- For new features
- Merged to main when complete
- Deleted after merge
Hotfix Branches: hotfix/issue-description
- For critical bug fixes
- Merged to main
- Tagged immediately
V1 Simple Workflow (current):
main branch only
|
|-- feature work ---> commit ---> tag v0.1.0
|
|-- more features --> commit ---> tag v0.2.0
|
|-- ready for 1.0 -> commit ---> tag v1.0.0
|
|-- bug fix --------> commit ---> tag v1.0.1
Release Process
Step-by-step:
-
Ensure all changes are committed and tested
git status pytest -
Update version in code
# Edit starpunk/__init__.py __version__ = "1.0.0" # Edit pyproject.toml (if exists) version = "1.0.0" -
Update CHANGELOG.md
# Add release notes (see Changelog Format below) -
Commit version bump
git add starpunk/__init__.py pyproject.toml CHANGELOG.md git commit -m "Bump version to 1.0.0" -
Create annotated tag
git tag -a v1.0.0 -m "Release 1.0.0: First stable release - IndieAuth authentication - Micropub support - RSS feed generation - File-based note storage - Basic web interface See CHANGELOG.md for full details." -
Push to repository
git push origin main git push origin v1.0.0 -
Create GitHub release (if applicable)
- Go to GitHub Releases
- Create release from tag v1.0.0
- Add release notes
- Attach any binaries (not needed for Python)
Changelog Format
File Location
Path: /home/phil/Projects/starpunk/CHANGELOG.md
Purpose: Human-readable record of all notable changes
Format
Based on Keep a Changelog
Structure:
# Changelog
All notable changes to StarPunk will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- Work in progress features
### Changed
- Work in progress changes
### Fixed
- Work in progress fixes
## [1.1.0] - 2024-12-01
### Added
- Tags support for organizing notes
- New `/api/tags` endpoint
- Tag filtering on homepage
### Changed
- Improved RSS feed performance
- Updated markdown rendering library
### Fixed
- RSS feed date format now RFC-822 compliant
- Session timeout handling
### Security
- Updated dependencies to patch vulnerabilities
## [1.0.1] - 2024-11-20
### Fixed
- Corrected RSS feed date formatting
- Fixed slug generation for non-ASCII content
### Security
- Patched XSS vulnerability in note rendering
## [1.0.0] - 2024-11-18
### Added
- IndieAuth authentication via IndieLogin
- Micropub endpoint for publishing
- RSS feed generation
- File-based note storage (Markdown)
- SQLite metadata database
- Web admin interface
- Public note viewing
- Slug generation and uniqueness
- Session management
- Basic security headers
[Unreleased]: https://github.com/username/starpunk/compare/v1.1.0...HEAD
[1.1.0]: https://github.com/username/starpunk/compare/v1.0.1...v1.1.0
[1.0.1]: https://github.com/username/starpunk/compare/v1.0.0...v1.0.1
[1.0.0]: https://github.com/username/starpunk/releases/tag/v1.0.0
Entry Categories
Added - New features Changed - Changes to existing functionality Deprecated - Features that will be removed in future versions Removed - Features that have been removed Fixed - Bug fixes Security - Security vulnerability fixes
Writing Changelog Entries
Good Entries (clear, specific, user-focused):
### Added
- Tags support for organizing notes with `/api/tags` endpoint
- Dark mode toggle in user preferences
### Fixed
- RSS feed now uses RFC-822 date format as required by spec
- Micropub endpoint returns correct HTTP 201 status code
Bad Entries (vague, technical, unclear):
### Added
- New feature
### Fixed
- Bug fixes
- Various improvements
Communication Strategy
Version Display
In Web Interface:
<!-- Footer of all pages -->
<footer>
StarPunk v1.0.0
<a href="https://github.com/username/starpunk/releases/tag/v1.0.0">Release Notes</a>
</footer>
In CLI:
$ python -m starpunk --version
StarPunk 1.0.0
In API:
GET /api/info HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"name": "StarPunk",
"version": "1.0.0",
"micropub_endpoint": "/api/micropub",
"indieauth_endpoint": "https://indielogin.com/auth"
}
In HTTP Headers (optional):
HTTP/1.1 200 OK
X-StarPunk-Version: 1.0.0
In User-Agent (when making HTTP requests):
User-Agent: StarPunk/1.0.0 (https://github.com/username/starpunk)
Release Announcements
Channels:
- GitHub Releases (primary)
- README.md (update version badge)
- Personal website/blog (optional)
- IndieWeb community (optional)
Template:
# StarPunk 1.0.0 Released
I'm excited to announce the first stable release of StarPunk, a minimal IndieWeb CMS!
## What's New
- Full IndieAuth authentication
- Micropub endpoint for publishing from any client
- RSS feed for syndication
- File-based storage (your notes, your files)
- Lightweight and self-hostable
## Upgrade Instructions
This is the first stable release. If you're upgrading from a development version (0.x):
1. Backup your `data/` directory
2. Pull the latest code: `git pull origin main`
3. Check for any configuration changes in `.env.example`
4. Restart the application
## Download
- [Source code](https://github.com/username/starpunk/archive/refs/tags/v1.0.0.zip)
- [Installation instructions](https://github.com/username/starpunk#quick-start)
## Changelog
See [CHANGELOG.md](https://github.com/username/starpunk/blob/v1.0.0/CHANGELOG.md) for full details.
Deprecation Warnings
When to Warn:
- One MINOR version before removal (e.g., deprecated in 1.1.0, removed in 2.0.0)
- At least 6 months notice (for longer release cycles)
How to Warn:
In Documentation:
## Configuration
### `OLD_SETTING` (Deprecated)
**Status**: Deprecated in v1.1.0, will be removed in v2.0.0
**Replacement**: Use `NEW_SETTING` instead
**Migration**:
```env
# Old (deprecated)
OLD_SETTING=value
# New
NEW_SETTING=value
**In Application Logs**:
```python
import warnings
if config.get('OLD_SETTING'):
warnings.warn(
"OLD_SETTING is deprecated and will be removed in StarPunk 2.0.0. "
"Use NEW_SETTING instead.",
DeprecationWarning,
stacklevel=2
)
In Changelog:
### Deprecated
- `OLD_SETTING` configuration option (use `NEW_SETTING` instead)
- Will be removed in v2.0.0
Upgrade Guides
Location: docs/upgrade/
Files:
docs/upgrade/0.x-to-1.0.md- Development to stabledocs/upgrade/1.x-to-2.0.md- Major version upgrade
Template:
# Upgrading from 0.x to 1.0
## Overview
StarPunk 1.0 is the first stable release. This guide helps you upgrade from development versions (0.x).
## Breaking Changes
### Configuration Format
**Change**: Configuration moved from JSON to .env file
**Action Required**:
1. Create `.env` file from `.env.example`
2. Migrate settings from old `config.json`
3. Delete `config.json`
### Database Schema
**Change**: Added `content_hash` column to `notes` table
**Action Required**:
Run migration script:
```bash
python scripts/migrate_0x_to_10.py
New Features
- IndieAuth authentication
- Micropub endpoint
- RSS feed
See CHANGELOG.md for full details.
Step-by-Step Upgrade
-
Backup your data:
cp -r data/ data-backup-$(date +%Y%m%d)/ -
Pull latest code:
git pull origin main git checkout v1.0.0 -
Update dependencies:
uv pip install -r requirements.txt -
Migrate configuration:
cp .env.example .env # Edit .env with your settings -
Run database migration:
python scripts/migrate_0x_to_10.py -
Test:
pytest flask --app app.py run # Visit http://localhost:5000 and verify -
Restart production:
sudo systemctl restart starpunk
Rollback
If you encounter issues:
- Stop application
- Restore backup:
cp -r data-backup-*/ data/ - Checkout previous version:
git checkout v0.9.0 - Restart application
Support
## Version Management in Code
### Primary Version Storage
**File**: `starpunk/__init__.py`
```python
"""
StarPunk - Minimal IndieWeb CMS
Version: 1.0.0
"""
__version__ = "1.0.0"
__version_info__ = (1, 0, 0)
# Make version easily importable
from starpunk import __version__
Usage:
from starpunk import __version__
print(f"StarPunk version {__version__}")
Package Metadata
File: pyproject.toml (if using)
[project]
name = "starpunk"
version = "1.0.0"
description = "Minimal IndieWeb CMS"
authors = [
{name = "Your Name", email = "your.email@example.com"}
]
dependencies = [
"flask>=3.0.0",
# ... other dependencies
]
[project.urls]
Homepage = "https://github.com/username/starpunk"
Repository = "https://github.com/username/starpunk"
Changelog = "https://github.com/username/starpunk/blob/main/CHANGELOG.md"
Keeping Versions in Sync
Problem: Version defined in multiple places (__init__.py, pyproject.toml, Git tags)
Solution: Single source of truth in starpunk/__init__.py
Implementation:
Option 1 - Manual sync (simple, V1):
# Update version in __init__.py
# Update version in pyproject.toml manually
# Commit and tag
Option 2 - Automated sync (V2+):
# Use bumpversion/bump2version tool
pip install bump2version
# Configure in .bumpversion.cfg
[bumpversion]
current_version = 1.0.0
commit = True
tag = True
[bumpversion:file:starpunk/__init__.py]
[bumpversion:file:pyproject.toml]
# Then bump version with:
bump2version patch # 1.0.0 -> 1.0.1
bump2version minor # 1.0.1 -> 1.1.0
bump2version major # 1.1.0 -> 2.0.0
V1 Decision: Manual sync (simple, no extra dependencies)
Version Check Utility
File: starpunk/utils.py (or dedicated starpunk/version.py)
from starpunk import __version__, __version_info__
def get_version() -> str:
"""Get StarPunk version string"""
return __version__
def get_version_info() -> tuple:
"""Get StarPunk version as tuple (major, minor, patch)"""
return __version_info__
def check_version_compatibility(min_version: str) -> bool:
"""
Check if current version meets minimum requirement
Args:
min_version: Minimum version required (e.g., "1.0.0")
Returns:
True if current version >= min_version
"""
min_parts = tuple(int(x) for x in min_version.split('.'))
return __version_info__ >= min_parts
CLI Version Display
Implementation:
# In app.py or starpunk/cli.py
import click
from starpunk import __version__
@click.group()
@click.version_option(version=__version__, prog_name="StarPunk")
def cli():
"""StarPunk - Minimal IndieWeb CMS"""
pass
if __name__ == '__main__':
cli()
Usage:
$ python app.py --version
StarPunk, version 1.0.0
Development Workflow
Starting New Development
After Release:
-
Create new section in CHANGELOG.md:
## [Unreleased] ### Added ### Changed ### Fixed -
Continue developing on main branch
-
Track changes in
[Unreleased]section
Preparing for Release
Checklist:
- All features complete and tested
- All tests pass
- Documentation updated
- CHANGELOG.md updated with release date
- Version bumped in
starpunk/__init__.py - Version bumped in
pyproject.toml(if exists) - Migration scripts created (if needed)
- Upgrade guide written (if major/minor)
Release Testing
Pre-release:
- Create release branch:
git checkout -b release/v1.1.0 - Run full test suite:
pytest - Test upgrade from previous version
- Manual testing of all features
- Fix any bugs found
- Merge to main:
git checkout main && git merge release/v1.1.0 - Tag and release
Python Ecosystem Compliance
PEP 440 Compatibility
Reference: PEP 440 - Version Identification
Format: Our SemVer format is PEP 440 compliant:
MAJOR.MINOR.PATCH[{a|b|rc}N]
Examples:
1.0.0 - Final release
1.0.0a1 - Alpha (note: no dot before 'a')
1.0.0b2 - Beta
1.0.0rc1 - Release candidate
Difference from SemVer:
- SemVer:
1.0.0-alpha.1(hyphen and dot) - PEP 440:
1.0.0a1(no separators)
Decision: Use PEP 440 format for Python package compatibility
Git Tags: Still use v1.0.0-alpha.1 (hyphen allowed in Git tags, not in Python version)
Mapping:
Git Tag Python Version (__version__)
v1.0.0-alpha.1 "1.0.0a1"
v1.0.0-beta.2 "1.0.0b2"
v1.0.0-rc.1 "1.0.0rc1"
v1.0.0 "1.0.0"
Version Specifiers
For dependencies (requirements.txt, pyproject.toml):
# Exact version
starpunk==1.0.0
# Minimum version
starpunk>=1.0.0
# Compatible version (same major version)
starpunk~=1.0.0 # Allows 1.0.x, not 1.1.0
# Version range
starpunk>=1.0.0,<2.0.0
Current State and Transition
Current Terminology
Documentation References:
- "V1" - Overall first release goal
- "Phase 1.1", "Phase 1.2" - Implementation milestones
- "v1.1", "v2.0" - Future iteration references
Clarifications
Phases vs Versions:
-
Phases: Development milestones (internal planning)
- Phase 1.1: Core utilities (development version 0.1.0)
- Phase 1.2: Data models (development version 0.2.0)
- Phase 1.3: Web routes (development version 0.3.0)
- etc.
-
Versions: Public release numbers (external communication)
- 0.1.0, 0.2.0 - Development versions
- 1.0.0 - First stable release (when all V1 phases complete)
- 1.1.0, 1.2.0 - Feature releases
- 2.0.0 - Next major version
Mapping:
Implementation Phase → Version Number → Git Tag
Phase 1.1 complete → 0.1.0 → v0.1.0
Phase 1.2 complete → 0.2.0 → v0.2.0
Phase 1.3 complete → 0.3.0 → v0.3.0
Phase 2.1 complete → 0.4.0 → v0.4.0
All V1 phases done → 1.0.0 → v1.0.0
V1.1 features added → 1.1.0 → v1.1.0
V2.0 features added → 2.0.0 → v2.0.0
First Release Name
Question: What should the first production release be called?
Answer: 1.0.0
Rationale:
- Signals production-ready software
- Follows semantic versioning convention
- "V1" in documentation refers to the feature set, not the version number
- Version 1.0.0 implements the "V1 feature set"
Updating Documentation
Action Items:
- Update references from "V1", "V2" to "version 1.0", "version 2.0"
- Clarify that "V1" is a feature scope, not a version number
- Use version numbers (1.0.0, 1.1.0) in user-facing communication
- Use phases (Phase 1.1, Phase 1.2) in development documentation
Example Updates:
Before:
# V1 Features
- IndieAuth authentication
- Micropub support
After:
# Version 1.0 Features (V1 Scope)
- IndieAuth authentication
- Micropub support
FAQ
Q: When should I create version 1.0.0?
A: When all features planned for the first production release are complete, tested, and documented. For StarPunk, this means:
- All core features working (auth, publishing, RSS)
- Full test coverage
- Complete documentation
- Production deployment tested
- Ready for public use
Q: Can I skip 0.x versions and go straight to 1.0.0?
A: Yes, but not recommended for StarPunk. Since we're actively developing, 0.x versions signal "not yet production ready" and give us freedom to make breaking changes.
Q: Should I version my API separately?
A: Not needed for V1. Simple version numbers are sufficient. If you need to support multiple API versions simultaneously (e.g., breaking changes but maintain backward compatibility), consider API versioning in URLs (/api/v1/, /api/v2/).
Q: How do I handle hotfixes?
A:
- Create hotfix branch from tag:
git checkout -b hotfix/critical-bug v1.0.0 - Fix bug
- Increment PATCH version: 1.0.0 → 1.0.1
- Tag:
v1.0.1 - Merge to main
- If developing next version, merge hotfix to develop branch too
Q: What if I need to change the database schema?
A:
- Backward compatible (adding optional column): MINOR version (1.0.0 → 1.1.0)
- Breaking change (removing column, changing format): MAJOR version (1.0.0 → 2.0.0)
- Provide migration script
- Document in upgrade guide
Q: How do I handle dependency updates?
A:
- Security patches: PATCH version (1.0.0 → 1.0.1)
- Minor updates (no feature changes): PATCH version
- Major updates (with feature changes): MINOR or MAJOR depending on impact
Q: Should I version documentation separately?
A: No. Documentation lives with code in Git. Version the whole repository together.
Q: What about version numbers for forks?
A: If someone forks StarPunk:
- They should use their own version numbers
- Or add suffix:
1.0.0-forkor1.0.0+myname.1 - Keep major.minor.patch in sync with upstream if merging changes
Q: How do I communicate breaking changes?
A:
- Increment MAJOR version
- Document in CHANGELOG under "Breaking Changes" section
- Provide upgrade guide
- Deprecate features one version early if possible
- Announce prominently in release notes
Q: Can I use dates in version numbers?
A: Not recommended. Calendar versioning (CalVer) like 2024.11.18 is valid but doesn't communicate change impact. Semantic versioning is clearer for StarPunk's use case.
Tools and Automation
Manual Version Management (V1)
Current Approach: Simple, manual versioning
Process:
- Edit
starpunk/__init__.py:__version__ = "1.0.0" - Edit
pyproject.toml:version = "1.0.0" - Update
CHANGELOG.md - Commit:
git commit -m "Bump version to 1.0.0" - Tag:
git tag -a v1.0.0 -m "Release 1.0.0" - Push:
git push origin main v1.0.0
Pros: Simple, no dependencies, full control Cons: Manual, error-prone, easy to forget steps
Automated Version Management (V2+)
Tools to Consider:
1. bump2version / bumpversion
pip install bump2version
# Configure in .bumpversion.cfg
bump2version patch # Increments, commits, tags automatically
2. python-semantic-release
pip install python-semantic-release
# Analyzes commit messages, determines version bump
semantic-release version
3. setuptools_scm
# Derives version from Git tags automatically
pip install setuptools_scm
V1 Decision: Manual versioning (simplest, aligns with indie philosophy)
V2+ Consideration: Add bump2version if versioning becomes tedious
Version Check on Install
Feature: Warn user if running outdated version
Implementation (optional, V2+):
import requests
from starpunk import __version__
def check_for_updates():
"""Check if a newer version is available"""
try:
response = requests.get(
"https://api.github.com/repos/username/starpunk/releases/latest",
timeout=2
)
latest = response.json()["tag_name"].lstrip('v')
if latest != __version__:
print(f"Update available: {latest} (you have {__version__})")
print("Visit: https://github.com/username/starpunk/releases")
except:
pass # Silently fail, don't block application
V1 Decision: Not needed (manual update check)
References
Standards
- Semantic Versioning 2.0.0 - Official SemVer spec
- PEP 440 - Python version identification
- Keep a Changelog - Changelog format
- Calendar Versioning - Alternative versioning (not used)
Tools
- bump2version - Version bump automation
- python-semantic-release - Semantic release automation
- setuptools_scm - SCM-based versioning
Examples
- Flask versioning - SemVer with PEP 440
- Django versioning - Modified SemVer
- Requests versioning - SemVer
Internal Documentation
Document Version: 1.0 Last Updated: 2024-11-18 Author: StarPunk Architecture Team Status: Active