Phil Skentelbery
e589f5bd6c
This commit resolves all documentation issues identified in the comprehensive review: CRITICAL FIXES: - Renumbered duplicate ADRs to eliminate conflicts: * ADR-022-migration-race-condition-fix → ADR-037 * ADR-022-syndication-formats → ADR-038 * ADR-023-microformats2-compliance → ADR-040 * ADR-027-versioning-strategy-for-authorization-removal → ADR-042 * ADR-030-CORRECTED-indieauth-endpoint-discovery → ADR-043 * ADR-031-endpoint-discovery-implementation → ADR-044 - Updated all cross-references to renumbered ADRs in: * docs/projectplan/ROADMAP.md * docs/reports/v1.0.0-rc.5-migration-race-condition-implementation.md * docs/reports/2025-11-24-endpoint-discovery-analysis.md * docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md * docs/decisions/ADR-044-endpoint-discovery-implementation.md - Updated README.md version from 1.0.0 to 1.1.0 - Tracked ADR-021-indieauth-provider-strategy.md in git DOCUMENTATION IMPROVEMENTS: - Created comprehensive INDEX.md files for all docs/ subdirectories: * docs/architecture/INDEX.md (28 documents indexed) * docs/decisions/INDEX.md (55 ADRs indexed with topical grouping) * docs/design/INDEX.md (phase plans and feature designs) * docs/standards/INDEX.md (9 standards with compliance checklist) * docs/reports/INDEX.md (57 implementation reports) * docs/deployment/INDEX.md (deployment guides) * docs/examples/INDEX.md (code samples and usage patterns) * docs/migration/INDEX.md (version migration guides) * docs/releases/INDEX.md (release documentation) * docs/reviews/INDEX.md (architectural reviews) * docs/security/INDEX.md (security documentation) - Updated CLAUDE.md with complete folder descriptions including: * docs/migration/ * docs/releases/ * docs/security/ VERIFICATION: - All ADR numbers now sequential and unique (50 total ADRs) - No duplicate ADR numbers remain - All cross-references updated and verified - Documentation structure consistent and well-organized These changes improve documentation discoverability, maintainability, and ensure proper version tracking. All index files follow consistent format with clear navigation guidance. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
50 lines
2.0 KiB
Markdown
50 lines
2.0 KiB
Markdown
# ADR-022: Multiple Syndication Format Support
|
|
|
|
## Status
|
|
Proposed
|
|
|
|
## Context
|
|
StarPunk currently provides RSS 2.0 feed generation using the feedgen library. The IndieWeb community and modern feed readers increasingly support additional syndication formats:
|
|
- ATOM feeds (RFC 4287) - W3C/IETF standard XML format
|
|
- JSON Feed (v1.1) - Modern JSON-based format gaining adoption
|
|
- Microformats2 - Already partially implemented for IndieWeb parsing
|
|
|
|
Multiple syndication formats increase content reach and client compatibility.
|
|
|
|
## Decision
|
|
Implement ATOM and JSON Feed support alongside existing RSS 2.0, maintaining all three formats in parallel.
|
|
|
|
## Rationale
|
|
1. **Low Implementation Complexity**: The feedgen library already supports ATOM generation with minimal code changes
|
|
2. **JSON Feed Simplicity**: JSON structure maps directly to our Note model, easier than XML
|
|
3. **Standards Alignment**: Both formats are well-specified and stable
|
|
4. **User Choice**: Different clients prefer different formats
|
|
5. **Minimal Maintenance**: Once implemented, feed formats rarely change
|
|
|
|
## Consequences
|
|
### Positive
|
|
- Broader client compatibility
|
|
- Better IndieWeb ecosystem integration
|
|
- Leverages existing feedgen dependency for ATOM
|
|
- JSON Feed provides modern alternative to XML
|
|
|
|
### Negative
|
|
- Three feed endpoints to maintain
|
|
- Slightly increased test surface
|
|
- Additional routes in API
|
|
|
|
## Alternatives Considered
|
|
1. **Single Universal Format**: Rejected - different clients have different preferences
|
|
2. **Content Negotiation**: Too complex for minimal benefit
|
|
3. **Plugin System**: Over-engineering for 3 stable formats
|
|
|
|
## Implementation Approach
|
|
1. ATOM: Use feedgen's built-in ATOM support (5-10 lines different from RSS)
|
|
2. JSON Feed: Direct serialization from Note models (~50 lines)
|
|
3. Routes: `/feed.xml` (RSS), `/feed.atom` (ATOM), `/feed.json` (JSON)
|
|
|
|
## Effort Estimate
|
|
- ATOM Feed: 2-4 hours (mostly testing)
|
|
- JSON Feed: 4-6 hours (new serialization logic)
|
|
- Tests & Documentation: 2-3 hours
|
|
- Total: 8-13 hours |