docs: Add upgrade guide for v1.1.2-rc.1

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-28 02:12:24 -07:00
parent dd63df7858
commit 34b576ff79
1 changed files with 328 additions and 0 deletions
--- a/docs/operations/upgrade-to-v1.1.2.md
+++ b/docs/operations/upgrade-to-v1.1.2.md
@@ -0,0 +1,328 @@
+# Upgrade Guide: StarPunk v1.1.2 "Syndicate"
+
+**Release Date**: 2025-11-27
+**Previous Version**: v1.1.1
+**Target Version**: v1.1.2-rc.1
+
+## Overview
+
+StarPunk v1.1.2 "Syndicate" adds multi-format feed support with content negotiation, caching, and comprehensive monitoring. This release is **100% backward compatible** with v1.1.1 - no breaking changes.
+
+### Key Features
+
+- **Multi-Format Feeds**: RSS 2.0, ATOM 1.0, JSON Feed 1.1 support
+- **Content Negotiation**: Smart format selection via HTTP Accept headers
+- **Feed Caching**: LRU cache with TTL and ETag support
+- **Feed Statistics**: Real-time monitoring dashboard
+- **OPML Export**: Subscription list for feed readers
+- **Metrics Instrumentation**: Complete monitoring foundation
+
+### What's New in v1.1.2
+
+#### Phase 1: Metrics Instrumentation
+- Database operation monitoring with query timing
+- HTTP request/response metrics with request IDs
+- Memory monitoring daemon thread
+- Business metrics framework
+- Configuration management
+
+#### Phase 2: Multi-Format Feeds
+- RSS 2.0: Fixed ordering bug, streaming + non-streaming generation
+- ATOM 1.0: RFC 4287 compliant with proper XML namespacing
+- JSON Feed 1.1: Spec compliant with custom _starpunk extension
+- Content negotiation via Accept headers
+- Multiple endpoints: `/feed`, `/feed.rss`, `/feed.atom`, `/feed.json`
+
+#### Phase 3: Feed Enhancements
+- LRU cache with 5-minute TTL
+- ETag support with 304 Not Modified responses
+- Feed statistics on admin dashboard
+- OPML 2.0 export at `/opml.xml`
+- Feed discovery links in HTML
+
+## Prerequisites
+
+Before upgrading:
+
+1. **Backup your data**:
+   ```bash
+   # Backup database
+   cp data/starpunk.db data/starpunk.db.backup
+
+   # Backup notes
+   cp -r data/notes data/notes.backup
+   ```
+
+2. **Check current version**:
+   ```bash
+   uv run python -c "import starpunk; print(starpunk.__version__)"
+   ```
+
+3. **Review changelog**: Read `CHANGELOG.md` for detailed changes
+
+## Upgrade Steps
+
+### Step 1: Stop StarPunk
+
+If running in production:
+
+```bash
+# For systemd service
+sudo systemctl stop starpunk
+
+# For container deployment
+podman stop starpunk  # or docker stop starpunk
+```
+
+### Step 2: Pull Latest Code
+
+```bash
+# From git repository
+git fetch origin
+git checkout v1.1.2-rc.1
+
+# Or download release tarball
+wget https://github.com/YOUR_USERNAME/starpunk/archive/v1.1.2-rc.1.tar.gz
+tar xzf v1.1.2-rc.1.tar.gz
+cd starpunk-1.1.2-rc.1
+```
+
+### Step 3: Update Dependencies
+
+```bash
+# Update Python dependencies with uv
+uv sync
+```
+
+**Note**: v1.1.2 requires `psutil` for memory monitoring. This will be installed automatically.
+
+### Step 4: Verify Configuration
+
+No new required configuration variables in v1.1.2, but you can optionally configure new features:
+
+```bash
+# Optional: Disable metrics (default: enabled)
+export METRICS_ENABLED=true
+
+# Optional: Configure metrics sampling rates
+export METRICS_SAMPLING_DATABASE=1.0    # 100% of database operations
+export METRICS_SAMPLING_HTTP=0.1        # 10% of HTTP requests
+export METRICS_SAMPLING_RENDER=0.1      # 10% of template renders
+
+# Optional: Configure memory monitoring interval (default: 30 seconds)
+export METRICS_MEMORY_INTERVAL=30
+
+# Optional: Disable feed caching (default: enabled)
+export FEED_CACHE_ENABLED=true
+
+# Optional: Configure feed cache size (default: 50 entries)
+export FEED_CACHE_MAX_SIZE=50
+
+# Optional: Configure feed cache TTL (default: 300 seconds / 5 minutes)
+export FEED_CACHE_SECONDS=300
+```
+
+### Step 5: Run Database Migrations
+
+StarPunk uses automatic migrations - no manual SQL needed:
+
+```bash
+# Migrations run automatically on startup
+# No database schema changes in v1.1.2
+uv run python -c "from starpunk import create_app; app = create_app(); print('Database ready')"
+```
+
+### Step 6: Restart StarPunk
+
+```bash
+# For systemd service
+sudo systemctl start starpunk
+sudo systemctl status starpunk
+
+# For container deployment
+podman start starpunk  # or docker start starpunk
+
+# For development
+uv run flask run
+```
+
+### Step 7: Verify Upgrade
+
+1. **Check version**:
+   ```bash
+   uv run python -c "import starpunk; print(starpunk.__version__)"
+   # Should output: 1.1.2-rc.1
+   ```
+
+2. **Test health endpoint**:
+   ```bash
+   curl http://localhost:5000/health
+   # Should return: {"status":"ok","version":"1.1.2-rc.1"}
+   ```
+
+3. **Test feed endpoints**:
+   ```bash
+   # RSS feed
+   curl http://localhost:5000/feed.rss
+
+   # ATOM feed
+   curl http://localhost:5000/feed.atom
+
+   # JSON Feed
+   curl http://localhost:5000/feed.json
+
+   # Content negotiation
+   curl -H "Accept: application/atom+xml" http://localhost:5000/feed
+
+   # OPML export
+   curl http://localhost:5000/opml.xml
+   ```
+
+4. **Check metrics dashboard** (requires authentication):
+   ```bash
+   # Visit http://localhost:5000/admin/metrics-dashboard
+   # Should show feed statistics section
+   ```
+
+5. **Run test suite** (optional):
+   ```bash
+   uv run pytest
+   # Should show: 766 tests passing
+   ```
+
+## New Features and Endpoints
+
+### Multi-Format Feed Endpoints
+
+- **`/feed`** - Content negotiation endpoint (respects Accept header)
+- **`/feed.rss`** or **`/feed.xml`** - Explicit RSS 2.0 feed
+- **`/feed.atom`** - Explicit ATOM 1.0 feed
+- **`/feed.json`** - Explicit JSON Feed 1.1
+- **`/opml.xml`** - OPML 2.0 subscription list
+
+### Content Negotiation
+
+The `/feed` endpoint now supports HTTP content negotiation:
+
+```bash
+# Request ATOM feed
+curl -H "Accept: application/atom+xml" http://localhost:5000/feed
+
+# Request JSON Feed
+curl -H "Accept: application/json" http://localhost:5000/feed
+
+# Request RSS feed (default)
+curl -H "Accept: */*" http://localhost:5000/feed
+```
+
+### Feed Caching
+
+All feed endpoints now support:
+- **ETag headers** for conditional requests
+- **304 Not Modified** responses for unchanged content
+- **LRU cache** with 5-minute TTL (configurable)
+- **Cache statistics** on admin dashboard
+
+Example:
+```bash
+# First request - generates feed and returns ETag
+curl -i http://localhost:5000/feed.rss
+# Response: ETag: W/"abc123..."
+
+# Subsequent request with If-None-Match
+curl -H 'If-None-Match: W/"abc123..."' http://localhost:5000/feed.rss
+# Response: 304 Not Modified (no body, saves bandwidth)
+```
+
+### Feed Statistics Dashboard
+
+Visit `/admin/metrics-dashboard` to see:
+- Requests by format (RSS, ATOM, JSON Feed)
+- Cache hit/miss rates
+- Feed generation performance
+- Format popularity (pie chart)
+- Cache efficiency (doughnut chart)
+- Auto-refresh every 10 seconds
+
+### OPML Subscription List
+
+The `/opml.xml` endpoint provides an OPML 2.0 subscription list containing all three feed formats:
+- No authentication required (public)
+- Compatible with all major feed readers
+- Discoverable via `<link>` tag in HTML
+
+## Performance Improvements
+
+### Feed Generation
+- **RSS streaming**: Memory-efficient generation for large feeds
+- **ATOM streaming**: RFC 4287 compliant streaming output
+- **JSON streaming**: Line-by-line JSON generation
+- **Generation time**: 2-5ms for 50 items
+
+### Caching Benefits
+- **Bandwidth savings**: 304 responses for repeat requests
+- **Cache overhead**: <1ms per request
+- **Memory bounded**: LRU cache limited to 50 entries
+- **TTL**: 5-minute cache lifetime (configurable)
+
+### Metrics Overhead
+- **Database monitoring**: Negligible overhead with connection pooling
+- **HTTP metrics**: 10% sampling (configurable)
+- **Memory monitoring**: Background daemon thread (30s interval)
+
+## Breaking Changes
+
+**None**. This release is 100% backward compatible with v1.1.1.
+
+### Deprecated Features
+
+- **`/feed.xml` redirect**: Still works but `/feed.rss` is preferred
+- **Old `/feed` endpoint**: Now supports content negotiation (still defaults to RSS)
+
+## Rollback Procedure
+
+If you need to rollback to v1.1.1:
+
+```bash
+# Stop StarPunk
+sudo systemctl stop starpunk  # or podman stop starpunk
+
+# Checkout v1.1.1
+git checkout v1.1.1
+
+# Restore dependencies
+uv sync
+
+# Restore database backup (if needed)
+cp data/starpunk.db.backup data/starpunk.db
+
+# Restart StarPunk
+sudo systemctl start starpunk  # or podman start starpunk
+```
+
+**Note**: No database schema changes in v1.1.2, so rollback is safe.
+
+## Known Issues
+
+None at this time. This is a release candidate - please report any issues.
+
+## Getting Help
+
+- **Documentation**: Check `/docs/` for detailed documentation
+- **Troubleshooting**: See `docs/operations/troubleshooting.md`
+- **GitHub Issues**: Report bugs and request features
+- **Changelog**: See `CHANGELOG.md` for detailed change history
+
+## What's Next
+
+After v1.1.2 stable release:
+- **v1.2.0**: Advanced features (Webmentions, media uploads)
+- **v2.0.0**: Multi-user support and significant architectural changes
+
+See `docs/projectplan/ROADMAP.md` for complete roadmap.
+
+---
+
+**Upgrade completed successfully!**
+
+Your StarPunk instance now supports multi-format feeds with caching and comprehensive monitoring.