StarPunk/docs/design/v1.0.0/v1.0.1-hotfix-plan.md

StarPunk v1.0.1 Hotfix Release Plan

Bug Description

Issue: Micropub Location header returns URL with double slash

• Severity: Medium (functional but aesthetically incorrect)
• Impact: Micropub clients receive malformed redirect URLs
• Example: https://starpunk.thesatelliteoflove.com//notes/slug-here

Version Information

• Current Version: v1.0.0 (released 2025-11-24)
• Fix Version: v1.0.1
• Type: PATCH (backward-compatible bug fix)
• Branch Strategy: hotfix/1.0.1-micropub-url

Root Cause

SITE_URL configuration includes trailing slash (required for IndieAuth), but Micropub handler adds leading slash when constructing URLs, resulting in double slash.

Fix Implementation

Code Changes Required

1. File: starpunk/micropub.py

Line 311 - In handle_create function:

# BEFORE:
permalink = f"{site_url}/notes/{note.slug}"

# AFTER:
permalink = f"{site_url}notes/{note.slug}"

Line 381 - In handle_query function:

# BEFORE:
"url": [f"{site_url}/notes/{note.slug}"],

# AFTER:
"url": [f"{site_url}notes/{note.slug}"],

Files to Update

1. starpunk/micropub.py - Fix URL construction (2 locations)
2. starpunk/init.py - Update version to "1.0.1"
3. CHANGELOG.md - Add v1.0.1 entry
4. tests/test_micropub.py - Add regression test for URL format

Implementation Steps

For Developer (using agent-developer)

1. Create hotfix branch:

   git checkout -b hotfix/1.0.1-micropub-url v1.0.0
   

2. Apply the fix:

   • Edit starpunk/micropub.py (remove leading slash in 2 locations)
   • Add comment explaining SITE_URL has trailing slash

3. Add regression test:

   • Test that Location header has no double slash
   • Test URL in Microformats2 response has no double slash

4. Update version:

   • starpunk/__init__.py: Change __version__ = "1.0.0" to "1.0.1"
   • Update __version_info__ = (1, 0, 1)

5. Update CHANGELOG.md:

   ## [1.0.1] - 2025-11-25
   
   ### Fixed
   - Micropub Location header no longer contains double slash in URL
   - Microformats2 query response URLs no longer contain double slash
   
   ### Technical Details
   - Fixed URL construction in micropub.py to account for SITE_URL trailing slash
   - Added regression tests for URL format validation
   

6. Run tests:

   uv run pytest tests/test_micropub.py -v
   uv run pytest  # Run full test suite
   

7. Commit changes:

   git add .
   git commit -m "Fix double slash in Micropub URL construction
   
   - Remove leading slash when constructing URLs with SITE_URL
   - SITE_URL already includes trailing slash per IndieAuth spec
   - Fixes malformed Location header in Micropub responses
   
   Fixes double slash issue reported after v1.0.0 release"
   

8. Tag release:

   git tag -a v1.0.1 -m "Hotfix 1.0.1: Fix double slash in Micropub URLs
   
   Fixes:
   - Micropub Location header URL format
   - Microformats2 query response URL format
   
   See CHANGELOG.md for details."
   

9. Merge to main:

   git checkout main
   git merge hotfix/1.0.1-micropub-url --no-ff
   

10. Push changes:

    git push origin main
    git push origin v1.0.1
    

11. Clean up:

    git branch -d hotfix/1.0.1-micropub-url
    

12. Update deployment:

    • Pull latest changes on production server
    • Restart application
    • Verify fix with Micropub client

Testing Checklist

Pre-Release Testing

• Micropub create returns correct Location header (no double slash)
• Micropub query returns correct URLs (no double slash)
• Test with actual Micropub client (e.g., Quill)
• Verify with different SITE_URL configurations
• All existing tests pass
• New regression tests pass

Post-Release Verification

• Create post via Micropub client
• Verify redirect URL is correct
• Check existing notes still accessible
• RSS feed still works correctly
• No other URL construction issues

Time Estimate

• Code changes: 5 minutes
• Testing: 15 minutes
• Documentation updates: 10 minutes
• Release process: 10 minutes
• Total: ~40 minutes

Risk Assessment

• Risk Level: Low
• Rollback Plan: Revert to v1.0.0 tag if issues arise
• No database changes: No migration required
• No configuration changes: No user action required
• Backward compatible: Existing data unaffected

Additional Considerations

Future Prevention

1. Document SITE_URL convention: Add clear comments about trailing slash
2. Consider URL builder utility: For v2.0, consider centralized URL construction
3. Review other URL constructions: Audit codebase for similar patterns

Communication

• No urgent user notification needed (cosmetic issue)
• Update project README with latest version after release
• Note fix in any active discussions about the project

Alternative Approaches (Not Chosen)

1. Strip trailing slash at usage - Adds unnecessary processing
2. Change config format - Breaking change, not suitable for hotfix
3. Add URL utility function - Over-engineering for hotfix

Success Criteria

• Micropub clients receive properly formatted URLs
• No regression in existing functionality
• Clean git history with proper version tags
• Documentation updated appropriately

---

Release Manager Notes: This is a straightforward fix with minimal risk. The key is ensuring both locations in micropub.py are updated and properly tested before release.