Files

Phil Skentelbery e589f5bd6c docs: Fix ADR numbering conflicts and create comprehensive documentation indices

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>

2025-11-25 13:28:56 -07:00

2.0 KiB

Raw Blame History

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

Low Implementation Complexity: The feedgen library already supports ATOM generation with minimal code changes
JSON Feed Simplicity: JSON structure maps directly to our Note model, easier than XML
Standards Alignment: Both formats are well-specified and stable
User Choice: Different clients prefer different formats
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

Single Universal Format: Rejected - different clients have different preferences
Content Negotiation: Too complex for minimal benefit
Plugin System: Over-engineering for 3 stable formats

Implementation Approach

ATOM: Use feedgen's built-in ATOM support (5-10 lines different from RSS)
JSON Feed: Direct serialization from Note models (~50 lines)
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

2.0 KiB Raw Blame History