Simplify Release Management with Static YAML Configuration

[petecheslock]

Problem

The previous system queried the GitHub API during builds to fetch release information, which added complexity, required tokens to avoid rate limits, and slowed down builds. The release workflow was unclear and builds had external dependencies that could fail.

Solution

Replace API-based syncing with a simple static YAML file that gets updated manually (via a script) when cutting a release. The build process now just reads from this committed file—no API calls, no tokens, no external dependencies during builds.

Changes

Release Management

• Added components-data.yaml as the single source of truth for:
  • Release version, date, and URLs
  • Component list with descriptions, versions, and metadata
  • Repository locations and branch/tag information
• Created sync-release.mjs - a one-time script that queries the GitHub API to update the YAML file when cutting a release
• Removed release-info.json and the old github-api-utils.js (no longer needed)
• Removed GITHUB_TOKEN from CI workflow since builds no longer make API calls
• Updated component-configs.js to load from YAML instead of hardcoded arrays
• Added js-yaml dependency for YAML parsing

Guide Versioning

• Modified guide-generator.js to fetch guides from release tags (e.g., v0.3.0) instead of main branch
  • Ensures guides match the actual released version users are installing
  • Users get accurate installation instructions for their version
• Disabled path versioning logic since we're not using Docusaurus versioning yet (but prepared for future use)

Source Attribution

• Updated footer callouts to differentiate between versioned and non-versioned content:
  • Versioned docs (components, guides) link to the specific release tag
  • Show clear guidance on where to find latest development changes
  • Non-versioned docs (community) link to main branch
• Fixed YAML escaping and newline handling issues in footer rendering

Documentation

• Comprehensive README overhaul with new sections:
  • "How It Works" - explains the remote content system architecture
  • "File Structure" - visual guide to the directory layout
  • "Cutting a New Release" - step-by-step workflow with examples
  • "Adding New Components" - YAML-based instructions
  • "Adding New Content Sources" - template-based approach
  • "Troubleshooting" - common issues and solutions table
• Updated CONTRIBUTING.md to reference README and use YAML examples
• Cleaned up docs/community/events.md - removed past events (Oct 2025 IBM TechXchange, All Things Open)

Release Workflow

When a new llm-d release is published, the process is now crystal clear:

# Step 1: Update the YAML file (queries GitHub API once)
cd remote-content/remote-sources
node sync-release.mjs
git diff components-data.yaml      # Review changes

# Step 2: Commit and deploy (triggers build that reads YAML)
git add components-data.yaml
git commit -m "Update to llm-d vX.Y.Z"
git push

Key distinction: The script queries the API → commits a static file → the build reads that file. No API calls during builds.

Content Synchronization Strategy

The documentation now uses three distinct synchronization strategies based on content type:

1. Components (/docs/architecture/Components/)

Sync from individual component release tags

• Each component's README syncs from its specific version tag mentioned in the llm-d release
• Examples:
  • llm-d-inference-scheduler → v0.3.2
  • llm-d-routing-sidecar → v0.3.0
  • llm-d-modelservice → llm-d-modelservice-v0.2.10 (special format)
• Why: Provides version-accurate documentation for each component as it existed at release time

2. Guides (/docs/guide/)

Sync from llm-d/llm-d release tag (e.g., v0.3.0)

• All installation and setup guides sync from the main llm-d release version
• Why: Ensures guides match the exact version users are installing

3. Community (/docs/community/)

Always sync from main branch

• Community documents (CODE_OF_CONDUCT, CONTRIBUTING, SECURITY, SIGS) always reflect current upstream
• Why: Provides up-to-date contribution guidelines and policies regardless of release version

[netlify]

✅ Deploy Preview for elaborate-kangaroo-25e1ee ready!

Name	Link
🔨 Latest commit	03470ea
🔍 Latest deploy log	https://app.netlify.com/projects/elaborate-kangaroo-25e1ee/deploys/68f14a6c82c642000857f201
😎 Deploy Preview	https://deploy-preview-109--elaborate-kangaroo-25e1ee.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.