StarPunk/docs/operations/upgrade-to-v1.1.2.md

# 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.