feat(docs-ui): add automated changelog sync from @backstage/ui

Adds automated synchronization of component changelogs from
@backstage/ui package to the documentation site, eliminating
manual changelog maintenance.

The sync script parses CHANGELOG.md using remark/unified, extracts
component-specific entries via "Affected components:" tags, and
generates per-version TypeScript files with preserved markdown
formatting. Includes GitHub API integration to automatically fetch
PR numbers for changelog entries.

Key features:
- Version comparison to sync only new releases
- Per-version file structure (changelogs/v0.2.0.ts, etc.)
- Markdown preservation via AST position slicing
- Component name mapping (PascalCase → kebab-case)
- Duplicate detection for idempotent syncing
- GitHub authentication via gh CLI or GITHUB_TOKEN
- Dry-run mode with preview

Usage:
```bash
yarn sync:changelog              # Sync new entries
yarn sync:changelog:dry-run      # Preview changes
```

Technical changes:
- Added scripts/sync-changelog.mjs (991 lines)
- Refactored changelog.ts to import per-version files
- Extracted types to separate types.ts file
- Added dependencies: @octokit/rest, unified (remark-parse via @mdx-js/mdx)
- Added documentation in README.md

Signed-off-by: Johan Persson <johanopersson@gmail.com>
This commit is contained in:
Johan Persson
2025-11-11 09:43:44 +01:00
parent e5e79ce4e9
commit 67f5310557
14 changed files with 1785 additions and 554 deletions
+23
View File
@@ -16,3 +16,26 @@ yarn add @backstage/ui
- [Backstage UI Documentation](https://ui.backstage.io)
- [Backstage Readme](https://github.com/backstage/backstage/blob/master/README.md)
- [Backstage Documentation](https://backstage.io/docs)
## Writing Changesets for Components
When creating changesets for component-specific changes, add component metadata to help maintain documentation:
```markdown
---
'@backstage/ui': patch
---
Fixed size prop handling for Avatar component.
Affected components: Avatar
```
**Guidelines:**
- **Component names**: Use PascalCase as they appear in imports (Avatar, ButtonIcon, SearchField)
- **Multiple components**: `Affected components: Button, ButtonLink, ButtonIcon`
- **General changes**: Omit the metadata line (build changes, package-level updates)
- **Placement**: The line can appear anywhere in the description
The changelog sync tool will parse these tags and update the documentation site automatically.