feat(tags): Add database schema and tags module (v1.3.0 Phase 1)
Implements tag/category system backend following microformats2 p-category specification. Database changes: - Migration 008: Add tags and note_tags tables - Normalized tag storage (case-insensitive lookup, display name preserved) - Indexes for performance New module: - starpunk/tags.py: Tag management functions - normalize_tag: Normalize tag strings - get_or_create_tag: Get or create tag records - add_tags_to_note: Associate tags with notes (replaces existing) - get_note_tags: Retrieve note tags (alphabetically ordered) - get_tag_by_name: Lookup tag by normalized name - get_notes_by_tag: Get all notes with specific tag - parse_tag_input: Parse comma-separated tag input Model updates: - Note.tags property (lazy-loaded, prefer pre-loading in routes) - Note.to_dict() add include_tags parameter CRUD updates: - create_note() accepts tags parameter - update_note() accepts tags parameter (None = no change, [] = remove all) Micropub integration: - Pass tags to create_note() (tags already extracted by extract_tags()) - Return tags in q=source response Per design doc: docs/design/v1.3.0/microformats-tags-design.md Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
190
docs/design/v1.0.0/v1.0.1-hotfix-plan.md
Normal file
190
docs/design/v1.0.0/v1.0.1-hotfix-plan.md
Normal file
@@ -0,0 +1,190 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user