feat: implement automated Bot SDK changelog system#4707
Conversation
OVERVIEW
--------
This PR introduces an automated changelog system that tracks and documents
all Bot SDK changes by analyzing git commit history. The system prioritizes
accuracy and safety over convenience by requiring manual verification for
all migration guides.
PROBLEM STATEMENT
-----------------
Developers building bots had no visibility into Bot SDK changes between
versions. Breaking changes would unexpectedly break production bots,
and developers had no migration instructions to fix their code.
SOLUTION
--------
Automated changelog generation with human-verified migration guides:
1. Git History Analysis
- Scans all commits since last release tag
- Filters to bot/SDK related commits only (packages/bot, packages/sdk, packages/towns-bot-cli)
- Categorizes by type: breaking changes, features, fixes, deprecations
2. Safety Mechanism
- Never auto-generates code examples (prevents incorrect migration instructions)
- Requires manual verification for all migration guides
- Shows affected files and links to commit diffs for transparency
- Displays 'Migration guide needed' for unverified breaking changes
3. GitHub Actions Automation
- Triggers on push to main when bot/SDK files change
- Auto-generates and commits changelog updates
- Uses [skip ci] to prevent infinite loops
FILES ADDED
-----------
Core System (3 files):
- scripts/generate-bot-sdk-changelog.ts (400 lines)
Main generator script, git history parser, categorization engine
- scripts/changelog-migration-guides.ts (38 lines)
Storage for manually verified migration guides
- scripts/CHANGELOG_MAINTAINER_GUIDE.md (302 lines)
Instructions for maintainers on adding verified migration guides
Automation (1 file):
- .github/workflows/bot-sdk-changelog.yml (60 lines)
GitHub Actions workflow for automatic changelog updates
Output (1 file):
- packages/docs/build/bots/changelog.mdx (190 lines)
Generated changelog documenting 640 bot/SDK commits
Visible at /build/bots/changelog in documentation
Documentation (3 files):
- BOT_SDK_CHANGELOG_README.md (287 lines)
Complete system documentation, usage guide, maintenance procedures
- CHANGES_SUMMARY.md (126 lines)
Quick reference of changes and statistics
- DOCS_CHANGELOG.md (160 lines)
Documentation tasks from main branch merge
FILES MODIFIED
--------------
- package.json: Added 'changelog' script and 'simple-git' dependency
- bun.lock: Locked simple-git@3.30.0
- packages/docs/docs.json: Added changelog to Bots navigation section
- packages/docs/build/miniapps/introduction.mdx: Updated to be framework-agnostic
TESTING PERFORMED
-----------------
1. Script Execution Test
- Successfully analyzed 1,567 total commits
- Correctly filtered to 640 bot/SDK commits (41%)
- Identified 6 breaking changes, 38 features, 18 fixes
2. File Generation Test
- Generated changelog.mdx with 190 lines
- Proper MDX formatting with frontmatter
- All sections present and correctly categorized
3. Navigation Test
- Verified changelog appears in documentation navigation
- Correct ordering in Bots section menu
4. Safety Feature Test
- Confirmed no auto-generated code examples
- Migration guides object empty by default
- Shows 'Migration guide needed' for breaking changes
5. TypeScript Compilation Test
- No type errors
- Readonly array handling fixed
6. GitHub Actions Configuration Test
- Workflow file syntax validated
- Trigger paths configured correctly
- Permissions set appropriately
STATISTICS
----------
- Commits analyzed: 1,567
- Bot/SDK commits: 640 (41%)
- Breaking changes: 6
- New features: 38
- Bug fixes: 18
- Deprecations: 1
- Execution time: 3-5 seconds
- Lines of code: ~500 TypeScript, ~60 YAML
- Lines of documentation: ~900
TECHNICAL DECISIONS
-------------------
1. Manual Migration Verification Required
Why: Prevents publishing incorrect migration instructions that would
mislead developers and waste their time debugging.
2. Shows Affected Files Instead of Guessing
Why: Transparency lets developers verify changes themselves rather than
trusting potentially incorrect automated suggestions.
3. Links to Commit Diffs
Why: Developers can review actual code changes to understand impact
on their implementations.
4. Separate Config for Migration Guides
Why: Makes it easy for maintainers to add verified guides without
touching generator logic.
USAGE
-----
For Developers:
View changelog at /build/bots/changelog in documentation
Update dependencies: bunx towns-bot update
For Maintainers:
Generate manually: bun run changelog
Add verified migration guide: Edit scripts/changelog-migration-guides.ts
NEXT STEPS
----------
After merge:
1. Monitor first GitHub Actions run
2. Verify auto-commit works correctly
3. Begin adding verified migration guides for breaking changes
4. Communicate new changelog location to bot developers
BREAKING CHANGES
----------------
None. This is a new feature that adds documentation capabilities.
Does not modify any existing bot SDK APIs or behavior.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
PR SummaryIntroduces an automated Bot SDK changelog system with a generator script, CI workflow to auto-update docs, and related documentation/navigation updates.
Written by Cursor Bugbot for commit 91507e4. This will update automatically on new commits. Configure here. |
Crisvond-hnt
requested review from
miguel-nascimento
and removed request for
Tee-S,
sergekh2 and
texuf
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. 📝 WalkthroughWalkthroughAdds an automated Bot SDK changelog system: generator and migration-guide registry, maintainer docs, a GitHub Actions workflow to generate and commit changelogs, a generated MDX changelog, and related docs/config updates. Changes
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes
Suggested reviewers
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
.github/workflows/bot-sdk-changelog.yml (1)
27-29: Consider pinning the Bun version.Using
bun-version: latestcan lead to unpredictable CI behavior if a new Bun version introduces breaking changes.- name: Setup Bun uses: oven-sh/setup-bun@v1 with: - bun-version: latest + bun-version: 1.1.xBOT_SDK_CHANGELOG_README.md (1)
29-29: Add language identifier to fenced code block.Specify a language for the ASCII diagram (e.g.,
textorplaintext).-``` +```text Developer Push (bot/SDK changes)scripts/generate-bot-sdk-changelog.ts (2)
112-112: Consider using proper types forgitparameter.Using
anyloses type safety. ImportSimpleGittype fromsimple-git.+import simpleGit, { SimpleGit } from 'simple-git' ... -async function filterBotSDKCommits(git: any, commits: any[]): Promise<CommitInfo[]> { +async function filterBotSDKCommits(git: SimpleGit, commits: any[]): Promise<CommitInfo[]> {
296-297: Unused variablenow.
nowis declared but never used.function generateChangelog(grouped: VersionChanges[]): string { - const now = new Date().toISOString().split('T')[0] - let md = `---CHANGES_SUMMARY.md (1)
76-76: Hyphenate compound adjective."Developer Friendly" should be "Developer-friendly" when used as a compound adjective modifying the noun phrase that follows.
-### Developer Friendly +### Developer-friendly
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
bun.lockis excluded by!**/*.lock,!bun.lockpackage.jsonis excluded by!package.json
📒 Files selected for processing (10)
.github/workflows/bot-sdk-changelog.yml(1 hunks)BOT_SDK_CHANGELOG_README.md(1 hunks)CHANGES_SUMMARY.md(1 hunks)DOCS_CHANGELOG.md(1 hunks)packages/docs/build/bots/changelog.mdx(1 hunks)packages/docs/build/miniapps/introduction.mdx(0 hunks)packages/docs/docs.json(1 hunks)scripts/CHANGELOG_MAINTAINER_GUIDE.md(1 hunks)scripts/changelog-migration-guides.ts(1 hunks)scripts/generate-bot-sdk-changelog.ts(1 hunks)
💤 Files with no reviewable changes (1)
- packages/docs/build/miniapps/introduction.mdx
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{ts,tsx,js,jsx,yaml,yml,sol,json,md}
📄 CodeRabbit inference engine (AGENTS.md)
All non-Go files (TypeScript, JavaScript, YAML, Solidity) must pass Prettier formatting by running
bun run prettier:fix
Files:
scripts/CHANGELOG_MAINTAINER_GUIDE.mdDOCS_CHANGELOG.mdscripts/generate-bot-sdk-changelog.tspackages/docs/docs.jsonBOT_SDK_CHANGELOG_README.mdscripts/changelog-migration-guides.tsCHANGES_SUMMARY.md
🧠 Learnings (6)
📚 Learning: 2025-11-25T08:44:36.255Z
Learnt from: CR
Repo: towns-protocol/towns PR: 0
File: packages/contracts/CLAUDE.md:0-0
Timestamp: 2025-11-25T08:44:36.255Z
Learning: Applies to packages/contracts/**/AGENTS.md : Maintain AGENTS.md file with agent documentation and guidelines
Applied to files:
scripts/CHANGELOG_MAINTAINER_GUIDE.md
📚 Learning: 2025-12-06T01:22:08.487Z
Learnt from: CR
Repo: towns-protocol/towns PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-06T01:22:08.487Z
Learning: Do NOT mention AI assistants or automated generation in git commit messages
Applied to files:
scripts/CHANGELOG_MAINTAINER_GUIDE.md
📚 Learning: 2025-11-25T08:48:39.130Z
Learnt from: CR
Repo: towns-protocol/towns PR: 0
File: packages/bot/AGENTS.md:0-0
Timestamp: 2025-11-25T08:48:39.130Z
Learning: Applies to packages/bot/**/*.{ts,tsx} : Pass the commands array to `makeTownsBot()` initialization in TypeScript bot setup files
Applied to files:
packages/docs/build/bots/changelog.mdxscripts/generate-bot-sdk-changelog.ts
📚 Learning: 2025-11-25T08:48:39.130Z
Learnt from: CR
Repo: towns-protocol/towns PR: 0
File: packages/bot/AGENTS.md:0-0
Timestamp: 2025-11-25T08:48:39.130Z
Learning: Applies to packages/bot/**/*.{ts,tsx} : Call `bot.start()` to obtain JWT middleware and handler for setting up the Towns webhook endpoint in Hono/Express TypeScript server files
Applied to files:
packages/docs/build/bots/changelog.mdx
📚 Learning: 2025-12-08T20:20:53.994Z
Learnt from: CR
Repo: towns-protocol/towns PR: 0
File: packages/examples/bot-quickstart/AGENTS.md:0-0
Timestamp: 2025-12-08T20:20:53.994Z
Learning: Applies to packages/examples/bot-quickstart/**/*.{ts,tsx} : Store required credentials (APP_PRIVATE_DATA and JWT_SECRET) as environment variables and pass them to makeTownsBot().
Applied to files:
packages/docs/build/bots/changelog.mdx
📚 Learning: 2025-11-25T08:48:39.130Z
Learnt from: CR
Repo: towns-protocol/towns PR: 0
File: packages/bot/AGENTS.md:0-0
Timestamp: 2025-11-25T08:48:39.130Z
Learning: Applies to packages/bot/**/*.{ts,tsx} : Import types `BotHandler`, `BasePayload`, and `MessageOpts` from `towns-protocol/bot` package when building abstractions and helper functions for bot handlers
Applied to files:
packages/docs/build/bots/changelog.mdx
🪛 LanguageTool
DOCS_CHANGELOG.md
[grammar] ~44-~44: Ensure spelling is correct
Context: ...ply Handling** (e273ed8) - SDK uses onchain free supply instead of hardcoding - ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
BOT_SDK_CHANGELOG_README.md
[grammar] ~21-~21: Use a hyphen to join words.
Context: ...*: Scans git history to find all bot/SDK related commits 2. Categorization: C...
(QB_NEW_EN_HYPHEN)
[uncategorized] ~67-~67: The official name of this software platform is spelled with a capital “H”.
Context: ...mplate and examples ### Automation .github/workflows/bot-sdk-changelog.yml - Tri...
(GITHUB)
CHANGES_SUMMARY.md
[uncategorized] ~15-~15: The official name of this software platform is spelled with a capital “H”.
Context: ...ce guide - Testing procedures 2. .github/workflows/bot-sdk-changelog.yml - ...
(GITHUB)
[uncategorized] ~76-~76: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...ry - No manual intervention needed ### Developer Friendly - Clear categorization (Breaking, Featu...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🪛 markdownlint-cli2 (0.18.1)
BOT_SDK_CHANGELOG_README.md
29-29: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
49-49: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
55-55: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
60-60: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
67-67: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
74-74: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
149-149: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
156-156: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
163-163: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
169-169: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: Cursor Bugbot
🔇 Additional comments (9)
packages/docs/docs.json (1)
153-153: LGTM!Changelog placed logically in the Bots navigation.
DOCS_CHANGELOG.md (1)
1-159: LGTM!Well-structured tracking document for pending documentation updates. The "onchain" spelling (line 44) is acceptable industry terminology.
scripts/changelog-migration-guides.ts (1)
33-37: LGTM!Empty-by-default design ensures no auto-generated migration content. Safe approach.
scripts/CHANGELOG_MAINTAINER_GUIDE.md (1)
1-301: LGTM!Comprehensive maintainer guide with clear templates and safety emphasis.
packages/docs/build/bots/changelog.mdx (1)
1-190: LGTM!Generated changelog follows safe patterns—no fabricated code examples, proper placeholders for migration guides.
scripts/generate-bot-sdk-changelog.ts (2)
162-173: Breaking change detection may produce false positives.The keywords
'removed'and'deprecated'inbreakingKeywordsmay match commits that aren't actually breaking (e.g., "removed unused import"). Consider requiringBREAKING CHANGE:in body or stricter patterns.
56-110: LGTM!Main function flow is clear: version detection → commit filtering → categorization → grouping → generation → output.
CHANGES_SUMMARY.md (2)
1-125: Verify Prettier formatting compliance.Per the coding guidelines, Markdown files must pass Prettier formatting by running
bun run prettier:fix. Please verify this file complies with Prettier standards.
1-125: Well-structured summary document.The file provides a clear, comprehensive overview of the Bot SDK Changelog System changes. The organization into sections (New Files, Modified Files, Key Features, Statistics, Testing, Usage, Next Steps) is logical and easy to follow. Content aligns with the PR objectives and accurately reflects the scope of changes. Safety-first philosophy is well-communicated.
ISSUES FIXED ------------ 1. Deprecation Misclassification - Removed 'deprecated' from breakingKeywords array - Deprecation commits now properly categorized as DEPRECATION - Before: 6 breaking changes (1 was actually deprecation) - After: 5 breaking changes (correct) - File: scripts/generate-bot-sdk-changelog.ts 2. Workflow First-Run Failure - Changed from 'git diff --quiet' to 'git status --porcelain' - Now detects newly generated untracked files - Changelog will be committed on first workflow run - File: .github/workflows/bot-sdk-changelog.yml 3. Workflow Error Masking - Replaced '|| true' with proper exit code checking - Only accepts exit code 1 (breaking changes) as non-error - Real errors now properly fail the workflow - Better debugging when genuine failures occur - File: .github/workflows/bot-sdk-changelog.yml 4. Hardcoded Local Path - Removed '/Users/crisvond/Towns-protocol/towns' from docs - Documentation now portable for all contributors - Uses 'from repository root' instructions - File: BOT_SDK_CHANGELOG_README.md TECHNICAL DETAILS ----------------- Script Changes (generate-bot-sdk-changelog.ts): - Line 13: Removed 'deprecated' from breakingKeywords - Deprecation check at lines 175-178 now runs correctly - Commits with 'deprecated' reach DEPRECATION classification Workflow Changes (bot-sdk-changelog.yml): - Lines 34-45: Proper exit code handling (0, 1, or error) - Lines 47-53: Use 'git status --porcelain' for change detection - Detects both modified tracked and new untracked files - Fails fast on genuine errors with correct exit codes Documentation Changes: - BOT_SDK_CHANGELOG_README.md: Generic path instructions - CHANGES_SUMMARY.md: Added bug fixes section with details TESTING ------- - Regenerated changelog: Now shows 5 breaking (was 6) - Exit code 1 for breaking changes (expected) - All files formatted with prettier - Ready for workflow testing on merge IMPACT ------ - More accurate commit categorization - Reliable first-run workflow execution - Better error reporting and debugging - Portable documentation for all devs
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (5)
scripts/generate-bot-sdk-changelog.ts (2)
68-75: Make the no-tag fallback robust for short histories.Using
HEAD~${CONFIG.defaultCommitLimit}when there are no tags can fail if the repo has fewer than that many commits. Consider falling back to “last N commits” viagit.log({ maxCount: CONFIG.defaultCommitLimit })instead of constructing a potentially invalid revision:- const tags = await git.tags() - const lastTag = tags.latest || `HEAD~${CONFIG.defaultCommitLimit}` - console.log(`Last tag: ${lastTag}`) - - // 3. Get commits since last tag - const log = await git.log({ from: lastTag, to: 'HEAD' }) + const tags = await git.tags() + let log + if (tags.latest) { + console.log(`Last tag: ${tags.latest}`) + log = await git.log({ from: tags.latest, to: 'HEAD' }) + } else { + console.log(`No tags found, using last ${CONFIG.defaultCommitLimit} commits`) + log = await git.log({ maxCount: CONFIG.defaultCommitLimit }) + }
297-303: Remove unusednowvariable fromgenerateChangelog.
nowis computed but never used; dropping it will keep the function clean and avoid unused-variable noise.- const now = new Date().toISOString().split('T')[0] - let md = `---BOT_SDK_CHANGELOG_README.md (3)
211-225: Clarify how to keyMIGRATION_GUIDESso lookups actually match.
extractMigrationGuideindexesMIGRATION_GUIDESby the cleaned message used as the changelog heading (after strippingfeat:/fix:prefixes and PR numbers), not the raw commit subject. The example here says"Exact commit message", which can be misleading.Suggest rephrasing to something like “Exact changelog heading (copy from the Breaking Changes section)” and updating the placeholder accordingly, so maintainers copy the value that the script will actually use as the key.
30-45: Optional: add a language to the architecture code block for markdown linters.The ASCII architecture block has a bare ``` fence; if you care about markdownlint/MD040, you can tag it as
text(or similar):-``` +```text Developer Push (bot/SDK changes)
288-295: Keep stats consistent with the single source of truth.The stats here (1,567 commits, 6 breaking, etc.) differ slightly from
CHANGES_SUMMARY.md(1,568 commits, 5 breaking). Consider picking one file as authoritative and updating the other to match to avoid confusion later.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
.github/workflows/bot-sdk-changelog.yml(1 hunks)BOT_SDK_CHANGELOG_README.md(1 hunks)CHANGES_SUMMARY.md(1 hunks)packages/docs/build/bots/changelog.mdx(1 hunks)scripts/generate-bot-sdk-changelog.ts(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- packages/docs/build/bots/changelog.mdx
- .github/workflows/bot-sdk-changelog.yml
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{ts,tsx,js,jsx,yaml,yml,sol,json,md}
📄 CodeRabbit inference engine (AGENTS.md)
All non-Go files (TypeScript, JavaScript, YAML, Solidity) must pass Prettier formatting by running
bun run prettier:fix
Files:
scripts/generate-bot-sdk-changelog.tsBOT_SDK_CHANGELOG_README.mdCHANGES_SUMMARY.md
🧬 Code graph analysis (1)
scripts/generate-bot-sdk-changelog.ts (1)
scripts/changelog-migration-guides.ts (1)
MIGRATION_GUIDES(33-37)
🪛 LanguageTool
BOT_SDK_CHANGELOG_README.md
[grammar] ~22-~22: Use a hyphen to join words.
Context: ...*: Scans git history to find all bot/SDK related commits 2. Categorization: C...
(QB_NEW_EN_HYPHEN)
[uncategorized] ~71-~71: The official name of this software platform is spelled with a capital “H”.
Context: ...mplate and examples ### Automation .github/workflows/bot-sdk-changelog.yml - Tr...
(GITHUB)
CHANGES_SUMMARY.md
[uncategorized] ~15-~15: The official name of this software platform is spelled with a capital “H”.
Context: ...ce guide - Testing procedures 2. .github/workflows/bot-sdk-changelog.yml - ...
(GITHUB)
🪛 markdownlint-cli2 (0.18.1)
BOT_SDK_CHANGELOG_README.md
30-30: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
50-50: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
57-57: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
63-63: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
71-71: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
79-79: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
163-163: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
172-172: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
181-181: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
189-189: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)
- GitHub Check: Common_CI
- GitHub Check: Multinode
- GitHub Check: Go_Tests
- GitHub Check: Multinode_Ent
- GitHub Check: Multinode_Ent_Legacy
- GitHub Check: Cursor Bugbot
- GitHub Check: XChain_Integration
🔇 Additional comments (1)
CHANGES_SUMMARY.md (1)
3-61: Summary matches the implemented system.The description of new/modified files and bug fixes (deprecation classification, workflow handling, hardcoded path) matches the current script and docs; nothing blocking here.
…codes CRITICAL ISSUES FIXED --------------------- 1. Incorrect Repository URL - Changed from 'river-build/river' to 'towns-protocol/towns' - All commit links in changelog now point to correct repository - Previously all 'View commit' links were broken - File: scripts/generate-bot-sdk-changelog.ts:11 2. Exit Code Collision - Changed error exit code from 1 to 2 - Exit code 1 reserved for breaking changes (expected) - Exit code 2 for real errors (git failures, missing files, etc.) - Workflow can now distinguish errors from breaking changes - Files: scripts/generate-bot-sdk-changelog.ts:402 3. Documentation Mismatch - Updated to reflect actual classification logic - 'removed' keyword is BREAKING, not deprecation - Added exit code documentation - File: BOT_SDK_CHANGELOG_README.md IMPACT ------ Before: - All commit links pointed to wrong repository (404 errors) - Errors silently treated as breaking changes in CI - Documentation didn't match actual behavior After: - All commit links work correctly - Errors properly fail the workflow - Documentation accurate and complete TESTING ------- Regenerated changelog: - Verified commit links point to towns-protocol/towns - Exit code 1 for breaking changes (expected) - 640 commits documented correctly Exit Code Behavior: - 0 = Success, no breaking changes - 1 = Success with breaking changes (workflow continues) - 2 = Error (workflow fails) FILES CHANGED ------------- - scripts/generate-bot-sdk-changelog.ts: Fixed repoUrl and exit code - BOT_SDK_CHANGELOG_README.md: Updated docs to match implementation - packages/docs/build/bots/changelog.mdx: Regenerated with correct links
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
BOT_SDK_CHANGELOG_README.md (1)
30-44: Tighten markdown to satisfy markdownlint (MD040/MD036).
- The architecture diagram fence at Lines 30–44 has no language; to satisfy MD040, consider
```text(or```bash/```mdwhere appropriate).- Several bold “headings” (e.g., file names around Lines 50–79 and test labels around Lines 174–200) trigger MD036; consider turning these into real headings (e.g.,
#### scripts/generate-bot-sdk-changelog.ts,#### Test 1: Generate Changelog) to keep markdownlint happy while preserving structure.Also applies to: 50-79, 174-200
scripts/generate-bot-sdk-changelog.ts (1)
67-75: UsemaxCountinstead of brittleHEAD~Nfallback for small repositories.When no tags exist, the code uses
HEAD~${CONFIG.defaultCommitLimit}as thefromref (line 69), which fails on repositories with fewer commits than the limit. For instance,HEAD~100..HEADwill error on a repo with fewer than 100 commits. Prefer amaxCount-based approach:git.log({ to: 'HEAD', maxCount: CONFIG.defaultCommitLimit })when!tags.latestto safely limit history regardless of commit depth.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
BOT_SDK_CHANGELOG_README.md(1 hunks)packages/docs/build/bots/changelog.mdx(1 hunks)scripts/generate-bot-sdk-changelog.ts(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/docs/build/bots/changelog.mdx
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{ts,tsx,js,jsx,yaml,yml,sol,json,md}
📄 CodeRabbit inference engine (AGENTS.md)
All non-Go files (TypeScript, JavaScript, YAML, Solidity) must pass Prettier formatting by running
bun run prettier:fix
Files:
scripts/generate-bot-sdk-changelog.tsBOT_SDK_CHANGELOG_README.md
🧠 Learnings (2)
📚 Learning: 2025-11-25T08:44:29.555Z
Learnt from: CR
Repo: towns-protocol/towns PR: 0
File: packages/bot/CLAUDE.md:0-0
Timestamp: 2025-11-25T08:44:29.555Z
Learning: Applies to packages/bot/**/AGENTS.md : All agent configurations and specifications should be documented in AGENTS.md
Applied to files:
BOT_SDK_CHANGELOG_README.md
📚 Learning: 2025-11-25T08:44:41.031Z
Learnt from: CR
Repo: towns-protocol/towns PR: 0
File: packages/examples/bot-quickstart/CLAUDE.md:0-0
Timestamp: 2025-11-25T08:44:41.031Z
Learning: Applies to packages/examples/bot-quickstart/**/AGENTS.md : Document agent configurations and behaviors in AGENTS.md
Applied to files:
BOT_SDK_CHANGELOG_README.md
🧬 Code graph analysis (1)
scripts/generate-bot-sdk-changelog.ts (1)
scripts/changelog-migration-guides.ts (1)
MIGRATION_GUIDES(33-37)
🪛 LanguageTool
BOT_SDK_CHANGELOG_README.md
[grammar] ~22-~22: Use a hyphen to join words.
Context: ...*: Scans git history to find all bot/SDK related commits 2. Categorization: C...
(QB_NEW_EN_HYPHEN)
[uncategorized] ~71-~71: The official name of this software platform is spelled with a capital “H”.
Context: ...mplate and examples ### Automation .github/workflows/bot-sdk-changelog.yml - Tr...
(GITHUB)
🪛 markdownlint-cli2 (0.18.1)
BOT_SDK_CHANGELOG_README.md
30-30: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
50-50: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
57-57: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
63-63: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
71-71: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
79-79: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
174-174: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
183-183: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
192-192: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
200-200: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)
- GitHub Check: Go_Tests
- GitHub Check: Multinode_Ent
- GitHub Check: Multinode_Ent_Legacy
- GitHub Check: Common_CI
- GitHub Check: Multinode
- GitHub Check: Cursor Bugbot
- GitHub Check: XChain_Integration
🔇 Additional comments (2)
BOT_SDK_CHANGELOG_README.md (1)
149-168: Change‑detection docs now align with implementation.The “Change Detection” bullets correctly describe the current detectChangeType logic (breaking/deprecation keywords and conventional prefixes), which keeps expectations in sync with the generator script.
scripts/generate-bot-sdk-changelog.ts (1)
96-109: Changelog generation + exit-code contract look solid.
1 participant
OVERVIEW
This PR introduces an automated changelog system that tracks and documents all Bot SDK changes by analyzing git commit history. The system prioritizes accuracy and safety over convenience by requiring manual verification for all migration guides.
PROBLEM STATEMENT
Developers building bots had no visibility into Bot SDK changes between versions. Breaking changes would unexpectedly break production bots, and developers had no migration instructions to fix their code.
SOLUTION
Automated changelog generation with human-verified migration guides:
Git History Analysis
Safety Mechanism
GitHub Actions Automation
FILES ADDED
Core System (3 files):
scripts/generate-bot-sdk-changelog.ts (400 lines) Main generator script, git history parser, categorization engine
scripts/changelog-migration-guides.ts (38 lines) Storage for manually verified migration guides
scripts/CHANGELOG_MAINTAINER_GUIDE.md (302 lines) Instructions for maintainers on adding verified migration guides
Automation (1 file):
Output (1 file):
Documentation (3 files):
BOT_SDK_CHANGELOG_README.md (287 lines) Complete system documentation, usage guide, maintenance procedures
CHANGES_SUMMARY.md (126 lines) Quick reference of changes and statistics
DOCS_CHANGELOG.md (160 lines) Documentation tasks from main branch merge
FILES MODIFIED
TESTING PERFORMED
Script Execution Test
File Generation Test
Navigation Test
Safety Feature Test
TypeScript Compilation Test
GitHub Actions Configuration Test
STATISTICS
TECHNICAL DECISIONS
Manual Migration Verification Required Why: Prevents publishing incorrect migration instructions that would mislead developers and waste their time debugging.
Shows Affected Files Instead of Guessing Why: Transparency lets developers verify changes themselves rather than trusting potentially incorrect automated suggestions.
Links to Commit Diffs Why: Developers can review actual code changes to understand impact on their implementations.
Separate Config for Migration Guides Why: Makes it easy for maintainers to add verified guides without touching generator logic.
USAGE
For Developers:
View changelog at /build/bots/changelog in documentation
Update dependencies: bunx towns-bot update
For Maintainers:
Generate manually: bun run changelog
Add verified migration guide: Edit scripts/changelog-migration-guides.ts
Description
Changes
Checklist