StarPunk/docs/projectplan/v1.3.1/RELEASE.md

StarPunk v1.3.1 Release

Status: Planning Codename: "Syndicate Tags" Focus: Feed Categories/Tags Support

Overview

This patch release adds tags/categories support to all three syndication feed formats (RSS 2.0, Atom 1.0, JSON Feed 1.1). Tags were added to the backend in v1.3.0 but are not currently included in feed output.

Features

Feed Categories/Tags Support

Add tag/category elements to all syndication feeds, enabling feed readers and aggregators to categorize and filter content by topic.

RSS 2.0 Categories

• Add <category> elements for each tag on a note
• Use display_name as element content for human readability
• Optional: Consider using normalized name as domain attribute for taxonomy identification
• Multiple <category> elements per item (one per tag)
• Reference: RSS 2.0 Specification (www.rssboard.org)

Example:

<item>
  <title>My Post</title>
  <category>Machine Learning</category>
  <category>Python</category>
</item>

Atom 1.0 Categories

• Add <category> elements with RFC 4287 compliance
• Required: term attribute (normalized tag name for machine processing)
• Optional: label attribute (display name for human readability)
• Optional: Consider scheme attribute for taxonomy URI
• Multiple <category> elements per entry (one per tag)
• Reference: RFC 4287 Section 4.2.2

Example:

<entry>
  <title>My Post</title>
  <category term="machine-learning" label="Machine Learning"/>
  <category term="python" label="Python"/>
</entry>

JSON Feed 1.1 Tags

• Add tags array to each item object
• Array contains display_name strings (human-readable)
• Empty array or omit field if no tags
• Reference: JSON Feed 1.1 Specification (jsonfeed.org)

Example:

{
  "items": [{
    "title": "My Post",
    "tags": ["Machine Learning", "Python"]
  }]
}

Implementation Scope

In Scope

• RSS feed category elements (starpunk/feeds/rss.py)
• Atom feed category elements (starpunk/feeds/atom.py)
• JSON Feed tags array (starpunk/feeds/json_feed.py)
• Load tags in feed generation routes (starpunk/routes/public.py)
• Unit tests for each feed format with tags
• Integration tests for feed generation with tagged notes

Out of Scope (Deferred)

• Tag-filtered feeds (e.g., /feed.rss?tag=python) - consider for v1.4.0
• Tag cloud/list in feeds - not part of feed specs
• Category hierarchy/taxonomy URIs - keep simple for v1

Technical Notes

Tag Data Loading

Notes are already loaded with include_tags=True capability in the model. Feed routes need to ensure tags are loaded when fetching notes:

• Check if get_note_tags() is called or if notes have .tags populated
• Pass tags to feed generation functions

Feed Generator Changes

Each feed module needs modification to accept and render tags:

1. RSS (generate_rss() / generate_rss_streaming()):

   • Accept tags from note object
   • Insert <category> elements after description/enclosure

2. Atom (generate_atom() / generate_atom_streaming()):

   • Accept tags from note object
   • Insert <category term="..." label="..."/> elements

3. JSON Feed (_build_item_object()):

   • Accept tags from note object
   • Add "tags": [...] array to item object

Backward Compatibility

• Tags are optional in all three feed specs
• Notes without tags will simply have no category/tags elements
• No breaking changes to existing feed consumers

Testing Requirements

Unit Tests

• RSS: Notes with tags generate correct <category> elements
• RSS: Notes without tags have no <category> elements
• RSS: Multiple tags generate multiple <category> elements
• Atom: Notes with tags generate correct <category> elements with term/label
• Atom: Notes without tags have no <category> elements
• JSON Feed: Notes with tags have tags array
• JSON Feed: Notes without tags have empty array or no tags field

Integration Tests

• Full feed generation with mix of tagged and untagged notes
• Feed validation against format specifications
• Streaming feed generation with tags

Dependencies

• v1.3.0 tags feature must be complete (database + backend)
• No new external dependencies required

Estimated Effort

• Small patch release (1-2 hours implementation)
• Focused scope: feed modifications only
• Well-defined specifications to follow

Success Criteria

1. All three feed formats include tags/categories when present
2. Feed output validates against respective specifications
3. Existing tests continue to pass
4. New tests cover tag rendering in feeds
5. No regression in feed generation performance

Related Documentation

• docs/architecture/syndication-architecture.md - Feed architecture overview
• docs/design/v1.3.0/microformats-tags-design.md - Tags feature design
• ADR-014: RSS Feed Implementation
• ADR-059: Full Feed Media Standardization (future media enhancements)

Standards References

• RSS 2.0 Specification - category element
• RFC 4287 - Atom Syndication Format (Section 4.2.2 for category)
• JSON Feed 1.1 Specification (tags field)