From 34b576ff7947e54418c190e24a6c17afb6efef12 Mon Sep 17 00:00:00 2001 From: Phil Skentelbery Date: Fri, 28 Nov 2025 02:12:24 -0700 Subject: [PATCH] docs: Add upgrade guide for v1.1.2-rc.1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/operations/upgrade-to-v1.1.2.md | 328 +++++++++++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 docs/operations/upgrade-to-v1.1.2.md diff --git a/docs/operations/upgrade-to-v1.1.2.md b/docs/operations/upgrade-to-v1.1.2.md new file mode 100644 index 0000000..ac82ee0 --- /dev/null +++ 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 `` 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.