Implement automated changelog management system for documentation updates

[Copilot]

Adds a changesets-inspired workflow for tracking documentation changes. Contributors create ephemeral changelog entries alongside doc updates, which are automatically aggregated and published weekly.

System Architecture

Entry Management

• .changelogs/entries/ - Ephemeral JSON entries (one per doc change)
• .changelogs/published/ - Archived entries post-publication
• .changelogs/schema.json - JSON schema for validation
• .changelogs/config.json - System configuration

CLI Tools (scripts/)

• changelog-add.js - Interactive entry creation with auto-generated IDs
• changelog-publish.js - Aggregates entries into dated MDX files
• changelog-validate.js - Schema validation

GitHub Actions Workflows

• changelog-entry-check.yml - Validates PRs touching docs include entries (or skip-changelog label)
• changelog-pr-helper.yml - Auto-suggests entries from PR title/description/changed files
• changelog-publish.yml - Weekly check (Mon 9AM UTC), publishes if entries exist

Entry Format

{
  "id": "1730322000000-abc123",
  "timestamp": "2025-10-30T20:00:00.000Z",
  "type": "added|changed|deprecated|removed|fixed|security",
  "title": "Brief user-facing description",
  "description": "Detailed explanation",
  "affectedDocs": [
    {
      "path": "docs/api-docs/cart.mdx",
      "url": "/docs/api-docs/cart",
      "title": "Cart API"
    }
  ],
  "author": "username",
  "prNumber": 123
}

Key Design Decisions

Direct Documentation Links

• Entries link to doc pages, not PRs
• URL auto-generated from file path via configurable mappings

Flexible Publishing Cadence

• Weekly automation checks for entries
• Publishes only when content exists (not fixed schedule)
• Creates PR for review before publishing

Developer Experience

• PR helper analyzes context, suggests entry content
• Validation catches issues early
• Skip label for typo/formatting-only changes

Usage

npm run changelog:add       # Interactive entry creation
npm run changelog:validate  # Validate entries
npm run changelog:publish   # Manual aggregation

Documentation

• .changelogs/README.md - Quick reference
• .changelogs/EXAMPLES.md - Usage examples
• docs/changelog/GUIDE.md - Complete contributor guide
• Updated CONTRIBUTING.md with changelog workflow
• Updated PR template with changelog reminder

Original prompt

You are an AI coding agent tasked with updating the dev docs site for automatic changelog management. Your goal is to implement a system similar to how changesets works in Catalyst, where changelog entries are created alongside doc updates and then aggregated for periodic publishing.

Here's what needs to be considered:

• Changelog Entry Creation: When a developer makes a functional change and updates/creates documentation, they should also create a corresponding changelog entry. This entry should be an ephemeral file, similar to how changesets creates randomly named files in a .changeset directory.
• Aggregation and Publishing: Implement an automation that aggregates these individual changelog entries and generates a comprehensive changelog. This should allow for publishing on a cadence (e.g., every two weeks) rather than on every PR merge.
• Linking to Documentation: The generated changelog entries should link directly to the relevant updated or new documentation pages, not to the pull requests. This requires a mechanism to determine the URL of the docs page from the PR context.
• Automation: The entire process, from creating the changelog entry to generating and potentially publishing the changelog, should be as automated as possible. This includes the ability to generate a draft PR for the changelog, similar to the version packages PR in Catalyst.
• Source Material Quality: Encourage product and engineering teams to provide high-quality source material (e.g., JIRA epic descriptions, GitHub pull request descriptions) as this can be leveraged to automatically generate initial draft changelog entries.
• Consider Existing Tools: Explore using or drawing inspiration from existing tools like changesets and the functionalities offered by platforms like Cloudflare's dev docs (which is open source) or Appwrite, specifically their approach to API references and overall developer experience.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[github-actions]

⚠️ [remark-lint] _{reported by reviewdog 🐶}
changesets is misspelt retext-spell retext-spell

[github-actions]

⚠️ [remark-lint] _{reported by reviewdog 🐶}
Link to /.changelogs/README is dead no-dead-urls remark-lint

[github-actions]

⚠️ [remark-lint] _{reported by reviewdog 🐶}
Link to /docs/changelog is dead no-dead-urls remark-lint

[github-actions]

⚠️ [remark-lint] _{reported by reviewdog 🐶}
️ is misspelt; did you mean a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z? retext-spell retext-spell

[github-actions]

⚠️ [remark-lint] _{reported by reviewdog 🐶}
️ is misspelt; did you mean a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z? retext-spell retext-spell

[github-actions]

⚠️ [remark-lint] _{reported by reviewdog 🐶}
Link to ./2025-10-30.mdx is dead no-dead-urls remark-lint