Phil Skentelbery
f10d0679da
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>
220 lines
6.8 KiB
Markdown
220 lines
6.8 KiB
Markdown
# StarPunk v1.1.2 Release Plan Options
|
|
|
|
## Executive Summary
|
|
|
|
Three distinct paths forward from v1.1.1 "Polish", each addressing the critical metrics instrumentation gap while offering different value propositions:
|
|
|
|
- **Option A**: "Observatory" - Complete observability with full metrics + distributed tracing
|
|
- **Option B**: "Syndicate" - Fix metrics + expand syndication with ATOM and JSON feeds
|
|
- **Option C**: "Resilient" - Fix metrics + add robustness features (backup/restore, rate limiting)
|
|
|
|
---
|
|
|
|
## Option A: "Observatory" - Complete Observability Stack
|
|
|
|
### Theme
|
|
Transform StarPunk into a fully observable system with comprehensive metrics, distributed tracing, and actionable insights.
|
|
|
|
### Scope
|
|
**12-14 hours**
|
|
|
|
### Features
|
|
- ✅ **Complete Metrics Instrumentation** (4 hours)
|
|
- Instrument all database operations with timing
|
|
- Add HTTP client/server request metrics
|
|
- Implement memory monitoring thread
|
|
- Add business metrics (notes created, syndication success rates)
|
|
|
|
- ✅ **Distributed Tracing** (4 hours)
|
|
- OpenTelemetry integration for request tracing
|
|
- Trace context propagation through all layers
|
|
- Correlation IDs for log aggregation
|
|
- Jaeger/Zipkin export support
|
|
|
|
- ✅ **Smart Alerting** (2 hours)
|
|
- Threshold-based alerts for key metrics
|
|
- Alert history and acknowledgment system
|
|
- Webhook notifications for alerts
|
|
|
|
- ✅ **Performance Profiling** (2 hours)
|
|
- CPU and memory profiling endpoints
|
|
- Flame graph generation
|
|
- Query analysis tools
|
|
|
|
### User Value
|
|
- **For Operators**: Complete visibility into system behavior, proactive problem detection
|
|
- **For Developers**: Easy debugging with full request tracing
|
|
- **For Users**: Better reliability through early issue detection
|
|
|
|
### Risks
|
|
- Requires learning OpenTelemetry concepts
|
|
- May add slight performance overhead (typically <1%)
|
|
- Additional dependencies for tracing libraries
|
|
|
|
---
|
|
|
|
## Option B: "Syndicate" - Enhanced Content Distribution
|
|
|
|
### Theme
|
|
Fix metrics and expand StarPunk's reach with multiple syndication formats, making content accessible to more readers.
|
|
|
|
### Scope
|
|
**14-16 hours**
|
|
|
|
### Features
|
|
- ✅ **Complete Metrics Instrumentation** (4 hours)
|
|
- Instrument all database operations with timing
|
|
- Add HTTP client/server request metrics
|
|
- Implement memory monitoring thread
|
|
- Add syndication-specific metrics
|
|
|
|
- ✅ **ATOM Feed Support** (4 hours)
|
|
- Full ATOM 1.0 specification compliance
|
|
- Parallel generation with RSS
|
|
- Content negotiation support
|
|
- Feed validation tools
|
|
|
|
- ✅ **JSON Feed Support** (4 hours)
|
|
- JSON Feed 1.1 implementation
|
|
- Author metadata support
|
|
- Attachment handling for media
|
|
- Hub support for real-time updates
|
|
|
|
- ✅ **Feed Enhancements** (2-4 hours)
|
|
- Feed statistics dashboard
|
|
- Custom feed URLs/slugs
|
|
- Feed caching layer
|
|
- OPML export for feed lists
|
|
|
|
### User Value
|
|
- **For Publishers**: Reach wider audience with multiple feed formats
|
|
- **For Readers**: Choose preferred feed format for their reader
|
|
- **For IndieWeb**: Better ecosystem compatibility
|
|
|
|
### Risks
|
|
- More complex content negotiation logic
|
|
- Feed format validation complexity
|
|
- Potential for feed generation performance issues
|
|
|
|
---
|
|
|
|
## Option C: "Resilient" - Operational Excellence
|
|
|
|
### Theme
|
|
Fix metrics and add critical operational features for data protection and system stability.
|
|
|
|
### Scope
|
|
**12-14 hours**
|
|
|
|
### Features
|
|
- ✅ **Complete Metrics Instrumentation** (4 hours)
|
|
- Instrument all database operations with timing
|
|
- Add HTTP client/server request metrics
|
|
- Implement memory monitoring thread
|
|
- Add backup/restore metrics
|
|
|
|
- ✅ **Backup & Restore System** (4 hours)
|
|
- Automated SQLite backup with rotation
|
|
- Point-in-time recovery
|
|
- Export to IndieWeb-compatible formats
|
|
- Restore validation and testing
|
|
|
|
- ✅ **Rate Limiting & Protection** (3 hours)
|
|
- Per-endpoint rate limiting
|
|
- Sliding window implementation
|
|
- DDoS protection basics
|
|
- Graceful degradation under load
|
|
|
|
- ✅ **Data Transformer Refactor** (1 hour)
|
|
- Fix technical debt from hotfix
|
|
- Implement proper contract pattern
|
|
- Add transformer tests
|
|
|
|
- ✅ **Operational Utilities** (2 hours)
|
|
- Database vacuum scheduling
|
|
- Log rotation configuration
|
|
- Disk space monitoring
|
|
- Graceful shutdown handling
|
|
|
|
### User Value
|
|
- **For Operators**: Peace of mind with automated backups and protection
|
|
- **For Users**: Data safety and system reliability
|
|
- **For Self-hosters**: Production-ready operational features
|
|
|
|
### Risks
|
|
- Backup strategy needs careful design to avoid data loss
|
|
- Rate limiting could affect legitimate users if misconfigured
|
|
- Additional background tasks may increase resource usage
|
|
|
|
---
|
|
|
|
## Comparison Matrix
|
|
|
|
| Aspect | Observatory | Syndicate | Resilient |
|
|
|--------|------------|-----------|-----------|
|
|
| **Primary Focus** | Observability | Content Distribution | Operational Safety |
|
|
| **Metrics Fix** | ✅ Complete | ✅ Complete | ✅ Complete |
|
|
| **New Features** | Tracing, Profiling | ATOM, JSON feeds | Backup, Rate Limiting |
|
|
| **Complexity** | High (new concepts) | Medium (new formats) | Low (straightforward) |
|
|
| **External Deps** | OpenTelemetry | Feed validators | None |
|
|
| **User Impact** | Indirect (better ops) | Direct (more readers) | Indirect (reliability) |
|
|
| **Performance** | Slight overhead | Neutral | Improved (rate limiting) |
|
|
| **IndieWeb Value** | Medium | High | Medium |
|
|
|
|
---
|
|
|
|
## Recommendation Framework
|
|
|
|
### Choose **Observatory** if:
|
|
- You're running multiple StarPunk instances
|
|
- You need to debug production issues
|
|
- You value deep system insights
|
|
- You're comfortable with observability tools
|
|
|
|
### Choose **Syndicate** if:
|
|
- You want maximum reader compatibility
|
|
- You're focused on content distribution
|
|
- You need modern feed formats
|
|
- You want to support more IndieWeb tools
|
|
|
|
### Choose **Resilient** if:
|
|
- You're running in production
|
|
- You value data safety above features
|
|
- You need protection against abuse
|
|
- You want operational peace of mind
|
|
|
|
---
|
|
|
|
## Implementation Notes
|
|
|
|
### All Options Include:
|
|
1. **Metrics Instrumentation** (identical across all options)
|
|
- Database operation timing
|
|
- HTTP request/response metrics
|
|
- Memory monitoring thread
|
|
- Business metrics relevant to option theme
|
|
|
|
2. **Version Bump** to v1.1.2
|
|
3. **Changelog Updates** following versioning strategy
|
|
4. **Documentation** for new features
|
|
5. **Tests** for all new functionality
|
|
|
|
### Phase Breakdown
|
|
|
|
Each option can be delivered in 2-3 phases:
|
|
|
|
**Phase 1** (4-6 hours): Metrics instrumentation + planning
|
|
**Phase 2** (4-6 hours): Core new features
|
|
**Phase 3** (4 hours): Polish, testing, documentation
|
|
|
|
---
|
|
|
|
## Decision Deadline
|
|
|
|
Please select an option by reviewing:
|
|
1. Your operational priorities
|
|
2. Your user community needs
|
|
3. Your comfort with complexity
|
|
4. Available time for implementation
|
|
|
|
Each option is designed to be completable in 2-3 focused work sessions while delivering distinct value to different stakeholder groups. |