StarPunk/docs/design/v1.1.2/critical-rss-ordering-fix.md

Critical: RSS Feed Ordering Regression Fix

Status: MUST FIX IN PHASE 2

Date Identified: 2025-11-26 Severity: CRITICAL - Production Bug Impact: All RSS feed consumers see oldest content first

The Bug

Current Behavior (INCORRECT)

RSS feeds are showing entries in ascending chronological order (oldest first) instead of the expected descending order (newest first).

Location

• File: /home/phil/Projects/starpunk/starpunk/feed.py
• Line 100: for note in reversed(notes[:limit]):
• Line 198: for note in reversed(notes[:limit]):

Root Cause

The code incorrectly applies reversed() to the notes list. The database already returns notes in DESC order (newest first), which is the correct order for feeds. The reversed() call flips this to ascending order (oldest first).

The misleading comment "Notes from database are DESC but feedgen reverses them, so we reverse back" is incorrect - feedgen does NOT reverse the order.

Expected Behavior

ALL feed formats MUST show newest entries first:

Format	Standard	Expected Order
RSS 2.0	Industry standard	Newest first
ATOM 1.0	RFC 4287 recommendation	Newest first
JSON Feed 1.1	Specification convention	Newest first

This is not optional - it's the universally expected behavior for all syndication formats.

Fix Implementation

Phase 2.0 - Fix RSS Feed Ordering (0.5 hours)

Step 1: Remove Incorrect Reversals

# Line 100 - BEFORE
for note in reversed(notes[:limit]):

# Line 100 - AFTER
for note in notes[:limit]:

# Line 198 - BEFORE
for note in reversed(notes[:limit]):

# Line 198 - AFTER
for note in notes[:limit]:

Step 2: Update/Remove Misleading Comments

Remove or correct the comment about feedgen reversing order.

Step 3: Add Comprehensive Tests

def test_rss_feed_newest_first():
    """Test RSS feed shows newest entries first"""
    old_note = create_note(title="Old", created_at=yesterday)
    new_note = create_note(title="New", created_at=today)

    feed = generate_rss_feed([new_note, old_note])
    items = parse_feed_items(feed)

    assert items[0].title == "New"
    assert items[1].title == "Old"

Prevention Strategy

1. Document Expected Behavior

All feed generator classes now include explicit documentation:

def generate(self, notes: List[Note], limit: int = 50):
    """Generate feed

    IMPORTANT: Notes are expected to be in DESC order (newest first)
    from the database. This order MUST be preserved in the feed.
    """

2. Implement Order Tests for All Formats

Every feed format specification now includes mandatory order testing:

• RSS: test_rss_feed_newest_first()
• ATOM: test_atom_feed_newest_first()
• JSON: test_json_feed_newest_first()

3. Add to Developer Q&A

Created CQ9 (Critical Question 9) in the developer Q&A document explicitly stating that newest-first is required for all formats.

Updated Documents

The following documents have been updated to reflect this critical fix:

1. docs/design/v1.1.2/implementation-guide.md

   • Added Phase 2.0 for RSS feed ordering fix
   • Added feed ordering tests to Phase 2 test requirements
   • Marked as CRITICAL priority

2. docs/design/v1.1.2/atom-feed-specification.md

   • Added order preservation documentation to generator
   • Added test_feed_order_newest_first() test
   • Added "DO NOT reverse" warning comments

3. docs/design/v1.1.2/json-feed-specification.md

   • Added order preservation documentation to generator
   • Added test_feed_order_newest_first() test
   • Added "DO NOT reverse" warning comments

4. docs/design/v1.1.2/developer-qa.md

   • Added CQ9: Feed Entry Ordering
   • Documented industry standards for each format
   • Included testing requirements

Verification Steps

After implementing the fix:

1. Generate RSS feed with multiple notes

2. Verify first entry has the most recent date

3. Test with popular feed readers:

   • Feedly
   • Inoreader
   • NewsBlur
   • The Old Reader

4. Run all feed ordering tests

5. Validate feeds with online validators

Timeline

This fix MUST be implemented at the beginning of Phase 2, before any work on ATOM or JSON Feed formats. The corrected RSS implementation will serve as the reference for the new formats.

Notes

This regression likely occurred due to a misunderstanding about how feedgen handles entry order. The lesson learned is to always verify assumptions about third-party libraries and to implement comprehensive tests for critical user-facing behavior like feed ordering.