StarPunk/docs/reports/ADR-019-versioning-guidance.md

# ADR-019 Implementation: Versioning Guidance

**Date**: 2025-11-19
**Author**: StarPunk Architect
**Status**: Final Recommendation

## Current Situation

**Current Version**: 0.7.1
**Released Tags**: v0.4.0, v0.5.2, v0.6.0, v0.6.1, v0.7.0, v0.7.1

**Problem**: ADR-019 initially suggested v0.6.3, but we have already released v0.7.0 and v0.7.1. We cannot go backward in semantic versioning (0.7.1 → 0.6.3 is invalid).

## What v0.7.0 and v0.7.1 Contained

### v0.7.0 (2025-11-19)
**Added**:
- IndieAuth detailed logging with token redaction
- OAuth Client ID Metadata Document endpoint (`/.well-known/oauth-authorization-server`)
  - **NOTE**: This endpoint is unnecessary and will be removed in ADR-019 implementation

**Changed**:
- Enhanced authentication flow visibility with structured logging
- LOG_LEVEL environment variable for configurable logging

**Security**:
- Automatic token redaction in logs

### v0.7.1 (2025-11-19)
**Fixed**:
- IndieAuth h-app visibility (removed `hidden` and `aria-hidden` attributes)
  - Made h-app microformat visible to parsers for backward compatibility
  - **NOTE**: h-app microformats are unnecessary and will be removed in ADR-019 implementation

## Analysis of Changes in ADR-019 Implementation

### What ADR-019 Will Do

**Fixes**:
1. Fix broken IndieAuth authentication (critical bug)
2. Add PKCE implementation (security enhancement, required by IndieLogin.com)
3. Correct API endpoints (/authorize and /token instead of /auth)
4. Add issuer validation

**Removes**:
1. OAuth metadata endpoint added in v0.7.0 (unnecessary)
2. h-app microformats modified in v0.7.1 (unnecessary)

**Changes**:
1. Database schema: adds `code_verifier` column to `auth_state` table
2. Authentication flow: implements PKCE properly

### Semantic Versioning Analysis

According to `/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md`:

**MAJOR** (x.0.0):
- Breaking API changes
- Database schema changes requiring migration ✓ (we have this)
- Configuration file format changes
- Removal of deprecated features

**MINOR** (0.x.0):
- New features (backward compatible)
- New API endpoints
- Non-breaking enhancements
- Optional configuration parameters

**PATCH** (0.0.x):
- Bug fixes
- Security patches
- Documentation corrections
- Dependency updates

**Special Rules for 0.x.y versions** (from versioning-strategy.md):
> "Public API should not be considered stable. Breaking changes allowed without major version increment."

During the 0.x phase, we have flexibility.

### Change Classification

**This implementation includes**:
1. **Critical bug fix** - Authentication completely broken
2. **Security enhancement** - PKCE implementation (best practice)
3. **Database schema change** - Adding column (backward compatible with DEFAULT)
4. **Feature removal** - OAuth metadata endpoint (added in v0.7.0, never worked)
5. **Code cleanup** - Removing unnecessary h-app microformats

**NOT included**:
- New user-facing features
- Breaking API changes for working features
- Configuration changes requiring user intervention

## Version Number Decision

### Recommended: v0.8.0 (MINOR Increment)

**Rationale**:

1. **Following 0.x Convention**: During the 0.x phase (pre-1.0), MINOR increments are used for both features and breaking changes. This is documented in our versioning strategy.

2. **This is a Significant Change**:
   - Fixes critical broken functionality
   - Adds PKCE (security enhancement)
   - Changes authentication flow
   - Modifies database schema
   - Removes features added in v0.7.0

3. **Database Schema Change**: While backward compatible (DEFAULT clause), schema changes traditionally warrant MINOR increment.

4. **Not a PATCH**: Too substantial for PATCH (0.7.2):
   - Not a simple bug fix
   - Adds new security mechanism (PKCE)
   - Removes endpoints
   - Changes multiple files and flow

5. **Not MAJOR (1.0.0)**: We're not ready for 1.0:
   - Still in development phase
   - V1 feature set not complete
   - This fixes existing planned functionality, doesn't complete the roadmap

### Version Progression Comparison

**Option A: v0.8.0 (RECOMMENDED)**
```
v0.7.0  → Logging + OAuth metadata (broken)
v0.7.1  → h-app visibility fix (unnecessary)
v0.8.0  → Fix IndieAuth with PKCE, remove unnecessary features
v1.0.0  → (Future) First stable release when all V1 features complete
```

**Option B: v0.7.2 (NOT RECOMMENDED)**
```
v0.7.0  → Logging + OAuth metadata (broken)
v0.7.1  → h-app visibility fix (unnecessary)
v0.7.2  → Fix IndieAuth with PKCE, remove unnecessary features
v1.0.0  → (Future) First stable release
```
Too minor for the scope of changes. PATCH should be simple fixes.

**Option C: v1.0.0 (NOT RECOMMENDED - TOO EARLY)**
```
v0.7.0  → Logging + OAuth metadata (broken)
v0.7.1  → h-app visibility fix (unnecessary)
v1.0.0  → Fix IndieAuth with PKCE, remove unnecessary features
```
Premature. Not all V1 features complete. 1.0.0 should signal "production ready."

## Git Tag Handling

### Recommendation: Keep All Existing Tags

**Do NOT delete v0.7.0 or v0.7.1**

**Rationale**:
1. **Git History Integrity**: Tags mark historical points. Deleting creates confusion.
2. **Semantic Versioning Rules**: You can't "un-release" a version.
3. **Traceability**: Keep record of what was attempted even if it didn't work.
4. **Documentation**: CHANGELOG will explain the situation clearly.

### What To Do Instead

**Mark v0.7.0 and v0.7.1 as broken in documentation**:
- CHANGELOG notes explain what didn't work
- GitHub release notes (if using) can be updated with warnings
- README or docs can reference the issue

## CHANGELOG Updates

### How to Document This

**Add v0.8.0 entry**:

```markdown
## [0.8.0] - 2025-11-19

### Fixed
- **CRITICAL**: Fixed IndieAuth authentication to work with IndieLogin.com
- Implemented required PKCE (Proof Key for Code Exchange) for security
- Corrected IndieLogin.com API endpoints (/authorize and /token)
- Added issuer validation for authentication callbacks

### Added
- PKCE code_verifier generation and storage
- PKCE code_challenge generation and validation
- Database column: auth_state.code_verifier for PKCE support

### Removed
- OAuth Client ID Metadata Document endpoint (/.well-known/oauth-authorization-server)
  - Added in v0.7.0 but unnecessary for IndieLogin.com
  - IndieLogin.com does not use OAuth client discovery
- h-app microformats markup from templates
  - Modified in v0.7.1 but unnecessary for IndieLogin.com
  - IndieLogin.com does not parse h-app for client identification
- indieauth-metadata link from HTML head

### Changed
- Authentication flow now follows IndieLogin.com API specification exactly
- Database schema: auth_state table includes code_verifier column
- State token validation now returns code_verifier for token exchange

### Security
- PKCE prevents authorization code interception attacks
- Issuer validation prevents token substitution attacks
- Code verifier securely stored and single-use

### Breaking Changes
- Users mid-authentication when upgrading will need to restart login (state tokens expire in 5 minutes)
- Existing state tokens without code_verifier will be invalid (intentional security improvement)

### Notes on Previous Versions
- **v0.7.0**: OAuth metadata endpoint added based on misunderstanding of requirements. This endpoint was never functional for our use case and is removed in v0.8.0.
- **v0.7.1**: h-app visibility changes attempted to fix authentication but addressed wrong issue. h-app discovery not used by IndieLogin.com. Removed in v0.8.0.
- **v0.8.0**: Correct implementation based on official IndieLogin.com API documentation.

### Related Documentation
- ADR-019: IndieAuth Correct Implementation Based on IndieLogin.com API
- Design Document: docs/designs/indieauth-pkce-authentication.md
- ADR-016: Superseded (h-app client discovery not required)
- ADR-017: Superseded (OAuth metadata not required)

### Migration Notes
- Database migration required: Add code_verifier column to auth_state table
- See docs/designs/indieauth-pkce-authentication.md for full implementation guide
```

**Update v0.7.0 entry with note**:

```markdown
## [0.7.0] - 2025-11-19

### Added
- **IndieAuth Detailed Logging**: Comprehensive logging for authentication flows
- Logging helper functions with automatic token redaction
- **OAuth Client ID Metadata Document endpoint** (/.well-known/oauth-authorization-server)
  - **NOTE (2025-11-19)**: This endpoint was added based on misunderstanding of IndieLogin.com requirements. IndieLogin.com does not use OAuth client discovery. This endpoint is removed in v0.8.0. See ADR-019 for correct implementation.

[... rest of v0.7.0 entry ...]

### Known Issues
- **IndieAuth authentication still broken**: This release attempted to fix authentication by adding OAuth metadata endpoint, but this is not required by IndieLogin.com. Missing PKCE implementation is the actual issue. Fixed in v0.8.0.
```

**Update v0.7.1 entry with note**:

```markdown
## [0.7.1] - 2025-11-19

### Fixed
- **IndieAuth h-app Visibility**: Removed `hidden` and `aria-hidden="true"` attributes from h-app microformat markup
  - h-app was invisible to IndieAuth parsers
  - **NOTE (2025-11-19)**: This fix attempted to enable client discovery, but IndieLogin.com does not use h-app microformats. h-app markup removed entirely in v0.8.0. See ADR-019 for correct implementation.

### Known Issues
- **IndieAuth authentication still broken**: This release attempted to fix authentication by making h-app visible, but IndieLogin.com does not parse h-app. Missing PKCE implementation is the actual issue. Fixed in v0.8.0.
```

## Version File Updates

### File: `/home/phil/Projects/starpunk/starpunk/__init__.py`

**Current** (line 156):
```python
__version__ = "0.7.1"
__version_info__ = (0, 7, 1)
```

**Change to**:
```python
__version__ = "0.8.0"
__version_info__ = (0, 8, 0)
```

### Git Tag Creation

**After implementation and testing complete**:

```bash
# Commit all changes
git add .
git commit -m "feat: Implement PKCE authentication for IndieLogin.com

- Add PKCE code_verifier and code_challenge generation
- Correct IndieLogin.com API endpoints (/authorize, /token)
- Add issuer validation
- Remove unnecessary OAuth metadata endpoint (from v0.7.0)
- Remove unnecessary h-app microformats (from v0.7.1)
- Update database schema: add auth_state.code_verifier column

Fixes critical IndieAuth authentication bug.
Version: 0.8.0

Related: ADR-019

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

# Create annotated tag
git tag -a v0.8.0 -m "Release 0.8.0: Fix IndieAuth Authentication with PKCE

Critical Fixes:
- Implemented PKCE (Proof Key for Code Exchange) as required by IndieLogin.com
- Corrected IndieLogin.com API endpoints
- Added issuer validation
- Fixed broken authentication flow

Removals:
- OAuth metadata endpoint (v0.7.0, unnecessary)
- h-app microformats (v0.7.1, unnecessary)

Security Enhancements:
- PKCE prevents authorization code interception
- Issuer validation prevents token substitution

Breaking Changes:
- Users mid-authentication must restart login after upgrade
- Database migration required (add auth_state.code_verifier column)

This release corrects authentication issues in v0.7.0 and v0.7.1 by implementing
the IndieLogin.com API specification correctly. See ADR-019 and design document
for full details.

See CHANGELOG.md for complete change details."

# Push
git push origin main
git push origin v0.8.0
```

## Summary: What the Developer Should Do

### 1. Version Number
**Use: 0.8.0**
- Update `starpunk/__init__.py`: `__version__ = "0.8.0"` and `__version_info__ = (0, 8, 0)`

### 2. Git Tags
**Keep all existing tags**: v0.4.0, v0.5.2, v0.6.0, v0.6.1, v0.7.0, v0.7.1
**Create new tag**: v0.8.0 after implementation complete

### 3. CHANGELOG Updates
- Add v0.8.0 entry with comprehensive details
- Update v0.7.0 entry with note about OAuth metadata being unnecessary
- Update v0.7.1 entry with note about h-app being unnecessary
- Explain the progression and corrections clearly

### 4. GitHub Release (if used)
- Create v0.8.0 release from tag
- Use tag message as release notes
- Optionally update v0.7.0 and v0.7.1 release descriptions with warnings

### 5. Documentation Updates
- ADR-016: Change status to "Superseded by ADR-019"
- ADR-017: Change status to "Superseded by ADR-019"
- ADR-005: Add implementation note referencing ADR-019

## Rationale for v0.8.0

**Why NOT v0.7.2 (PATCH)**:
- Too substantial (PKCE implementation, endpoint changes, removals)
- Database schema change
- Semantic versioning: PATCH should be simple fixes
- This is a significant rework, not a small fix

**Why NOT v1.0.0 (MAJOR)**:
- Not all V1 features complete yet
- Still in development phase (0.x series)
- 1.0.0 should signal "production ready, all planned features"
- This fixes existing planned functionality, doesn't complete roadmap

**Why v0.8.0 (MINOR)**:
- Appropriate for 0.x development phase
- Signals significant change from v0.7.x
- Follows project versioning strategy for 0.x phase
- Database schema change warrants MINOR
- Keeps clean numbering progression toward 1.0.0

## Version Roadmap

**Current Path**:
```
v0.7.0  - Logging + OAuth metadata (misunderstood requirements)
v0.7.1  - h-app visibility (wrong fix)
v0.8.0  - PKCE + correct IndieLogin.com implementation (THIS RELEASE)
v0.9.0  - (Future) Additional features or fixes
v1.0.0  - (Future) First stable release with all V1 features
```

This progression clearly shows:
1. v0.7.x attempted fixes based on wrong understanding
2. v0.8.0 correct implementation based on actual API requirements
3. Clean path to v1.0.0 when V1 scope is complete

---

**Decision**: Use v0.8.0
**Reasoning**: MINOR increment appropriate for significant fix with schema change during 0.x phase
**Action**: Update version to 0.8.0, create tag v0.8.0, update CHANGELOG with detailed notes
**Git Tags**: Keep all existing tags (v0.7.0, v0.7.1), add v0.8.0