StarPunk/docs/releases/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:
```python
# BEFORE:
permalink = f"{site_url}/notes/{note.slug}"

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

**Line 381** - In `handle_query` function:
```python
# 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**:
   ```bash
   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**:
   ```markdown
   ## [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**:
   ```bash
   uv run pytest tests/test_micropub.py -v
   uv run pytest  # Run full test suite
   ```

7. **Commit changes**:
   ```bash
   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**:
   ```bash
   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**:
   ```bash
   git checkout main
   git merge hotfix/1.0.1-micropub-url --no-ff
   ```

10. **Push changes**:
    ```bash
    git push origin main
    git push origin v1.0.1
    ```

11. **Clean up**:
    ```bash
    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.