feat: Add release notes generator workflow#105
Draft
jyejare wants to merge 1 commit intoambient-code:mainfrom
Draft
feat: Add release notes generator workflow#105jyejare wants to merge 1 commit intoambient-code:mainfrom
jyejare wants to merge 1 commit intoambient-code:mainfrom
Conversation
Adds a new workflow for generating structured release notes from git commits and tags with automatic categorization. Features: - Automatic categorization (features, bugs, breaking changes, enhancements) - PR number extraction from commit messages - Component detection (API, UI/UX, Database, CLI, etc.) - Professional markdown formatting with emoji indicators - Statistics generation and analytics - /generate command for quick invocation - Conversational mode for guided generation Technical Details: - Uses utility-mcp-server Python package - Automatic tool installation on first use - Outputs to artifacts/release-notes/ - Supports clickable PR/commit links when repo URL provided - Works with conventional commit format Workflow Structure: - .ambient/ambient.json - Workflow configuration - .claude/commands/generate.md - /generate slash command - CLAUDE.md - Persistent context and behavioral guidelines - README.md - User-facing documentation with examples - DEPLOYMENT.md - Complete deployment guide - QUICKSTART.md - Fast-track deployment instructions Output Location: artifacts/release-notes/ Ready for use via Custom Workflow or as official ACP workflow. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Contributor
WalkthroughA complete Release Notes Generator workflow is added to the repository, providing automated generation of structured release notes from git commit history between version tags. The workflow includes agent configuration, command definitions, comprehensive documentation, and deployment guidance for the Ambient Code Platform. Changes
Estimated Code Review Effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@workflows/release-notes-generator/.claude/commands/generate.md`:
- Around line 107-111: The current execute step changes into
artifacts/release-notes before running generate_<version>.py, but the script
itself calls Path("artifacts/release-notes").mkdir(...) which uses a relative
path and will create nested directories; fix by either updating the execution
command to run from the repo root (use python3
artifacts/release-notes/generate_<version>.py in the "Execute" section) or
modify the script generate_<version>.py to build an absolute path for the
artifacts directory (use
Path(__file__).resolve().parent.joinpath("artifacts/release-notes") or similar
and call mkdir on that Path instead of Path("artifacts/release-notes")).
- Around line 48-105: Summary: The script template uses placeholders (<VERSION>,
<PREVIOUS_VERSION>, <REPO_PATH>, <REPO_URL>) but doesn't tell users to replace
them. Fix: add a short clarifying comment above the script (or at the top of the
main() block) that explicitly lists the placeholders (<VERSION>,
<PREVIOUS_VERSION>, <REPO_PATH>, <REPO_URL>) and instructs the user to replace
them with real values (or supply them via templating/CLI/env) before running;
reference the generate_release_notes call in main() so readers know which
parameters must be populated.
In `@workflows/release-notes-generator/DEPLOYMENT.md`:
- Around line 12-25: Update the deployment snippet to remove the ambiguous
hard-coded path and make the source and destination consistent: replace the
reference to "/workspace/artifacts/release-notes-workflow" with a placeholder or
explanatory comment like "cd /path/to/your/release-notes-generator" and ensure
the subsequent copy command ("cp -r .
/path/to/workflows-repo/workflows/release-notes-generator/") clearly matches
that same source location; also add one short line explaining how users obtain
or generate the workflow files if they aren't already present so both the cd and
cp commands are unambiguous.
- Around line 151-157: The docs currently only mention Python 3.12+ under the
"Tool installation fails" troubleshooting section; add a "Prerequisites" section
near the top (before Quick Start) that explicitly lists Python 3.12+ (and
pip/internet access) or alternately update the "Verification Checklist" heading
to call out "Requires Python 3.12+" so users see the requirement earlier; update
headings referenced ("Quick Start", "Verification Checklist", and "Tool
installation fails") to ensure consistency and add a short note about verifying
python --version.
In `@workflows/release-notes-generator/install-command.sh`:
- Around line 6-14: The install script moves generate_command_temp.md to
.claude/commands/generate.md but doesn't ensure the target directory exists;
before calling mv (the block that handles generate_command_temp.md and
.claude/commands/generate.md), create the directory with a safe recursive mkdir
(e.g., mkdir -p .claude/commands) and handle any mkdir failures so the
subsequent mv succeeds and the existing echo/exit handling remains correct.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 740842b6-df9c-4882-861b-d3ccd73f4903
📒 Files selected for processing (11)
workflows/release-notes-generator/.ambient/ambient.jsonworkflows/release-notes-generator/.claude/commands/generate.mdworkflows/release-notes-generator/.gitignoreworkflows/release-notes-generator/ADD_GENERATE_COMMAND.mdworkflows/release-notes-generator/CLAUDE.mdworkflows/release-notes-generator/COMMAND_TEMPLATE.mdworkflows/release-notes-generator/COMPLETE.mdworkflows/release-notes-generator/DEPLOYMENT.mdworkflows/release-notes-generator/QUICKSTART.mdworkflows/release-notes-generator/README.mdworkflows/release-notes-generator/install-command.sh
Comment on lines
+48
to
+105
| ### 4. Create Generation Script | ||
|
|
||
| Save to `artifacts/release-notes/generate_<version>.py`: | ||
|
|
||
| ```python | ||
| #!/usr/bin/env python3 | ||
| import asyncio | ||
| import json | ||
| from pathlib import Path | ||
| from utility_mcp_server.src.tools.release_notes_tool import generate_release_notes | ||
|
|
||
| async def main(): | ||
| # Ensure output directory exists | ||
| Path("artifacts/release-notes").mkdir(parents=True, exist_ok=True) | ||
|
|
||
| # Generate release notes | ||
| result = await generate_release_notes( | ||
| version="<VERSION>", | ||
| previous_version="<PREVIOUS_VERSION>", | ||
| repo_path="<REPO_PATH>", | ||
| repo_url="<REPO_URL>", | ||
| release_date=None # Uses today's date | ||
| ) | ||
|
|
||
| if result.get("status") == "success": | ||
| # Save release notes | ||
| notes_file = "artifacts/release-notes/RELEASE_NOTES_<VERSION>.md" | ||
| with open(notes_file, "w") as f: | ||
| f.write(result["release_notes"]) | ||
| print(f"✅ Release notes saved to: {notes_file}") | ||
|
|
||
| # Save statistics | ||
| if "statistics" in result: | ||
| stats_file = "artifacts/release-notes/stats_<VERSION>.json" | ||
| with open(stats_file, "w") as f: | ||
| json.dump(result["statistics"], f, indent=2) | ||
| print(f"✅ Statistics saved to: {stats_file}") | ||
|
|
||
| # Display release notes | ||
| print("\n" + "="*80) | ||
| print(result["release_notes"]) | ||
| print("="*80 + "\n") | ||
|
|
||
| # Display statistics | ||
| if "statistics" in result: | ||
| print("📊 Statistics:") | ||
| for key, value in result["statistics"].items(): | ||
| print(f" {key}: {value}") | ||
|
|
||
| return result | ||
| else: | ||
| error_msg = result.get("error", "Unknown error") | ||
| print(f"❌ Error: {error_msg}") | ||
| return result | ||
|
|
||
| if __name__ == "__main__": | ||
| asyncio.run(main()) | ||
| ``` |
Contributor
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Clarify that placeholders must be replaced.
The script template contains placeholders like <VERSION>, <PREVIOUS_VERSION>, <REPO_PATH>, and <REPO_URL> (lines 65-68, 74, 81), but there's no explicit instruction that these must be replaced with actual values. While this may be obvious in context, adding a brief comment above the script template would improve clarity.
📝 Suggested documentation improvement
### 4. Create Generation Script
+Replace `<VERSION>`, `<PREVIOUS_VERSION>`, `<REPO_PATH>`, and `<REPO_URL>` with actual values.
+
Save to `artifacts/release-notes/generate_<version>.py`:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ### 4. Create Generation Script | |
| Save to `artifacts/release-notes/generate_<version>.py`: | |
| ```python | |
| #!/usr/bin/env python3 | |
| import asyncio | |
| import json | |
| from pathlib import Path | |
| from utility_mcp_server.src.tools.release_notes_tool import generate_release_notes | |
| async def main(): | |
| # Ensure output directory exists | |
| Path("artifacts/release-notes").mkdir(parents=True, exist_ok=True) | |
| # Generate release notes | |
| result = await generate_release_notes( | |
| version="<VERSION>", | |
| previous_version="<PREVIOUS_VERSION>", | |
| repo_path="<REPO_PATH>", | |
| repo_url="<REPO_URL>", | |
| release_date=None # Uses today's date | |
| ) | |
| if result.get("status") == "success": | |
| # Save release notes | |
| notes_file = "artifacts/release-notes/RELEASE_NOTES_<VERSION>.md" | |
| with open(notes_file, "w") as f: | |
| f.write(result["release_notes"]) | |
| print(f"✅ Release notes saved to: {notes_file}") | |
| # Save statistics | |
| if "statistics" in result: | |
| stats_file = "artifacts/release-notes/stats_<VERSION>.json" | |
| with open(stats_file, "w") as f: | |
| json.dump(result["statistics"], f, indent=2) | |
| print(f"✅ Statistics saved to: {stats_file}") | |
| # Display release notes | |
| print("\n" + "="*80) | |
| print(result["release_notes"]) | |
| print("="*80 + "\n") | |
| # Display statistics | |
| if "statistics" in result: | |
| print("📊 Statistics:") | |
| for key, value in result["statistics"].items(): | |
| print(f" {key}: {value}") | |
| return result | |
| else: | |
| error_msg = result.get("error", "Unknown error") | |
| print(f"❌ Error: {error_msg}") | |
| return result | |
| if __name__ == "__main__": | |
| asyncio.run(main()) | |
| ``` | |
| ### 4. Create Generation Script | |
| Replace `<VERSION>`, `<PREVIOUS_VERSION>`, `<REPO_PATH>`, and `<REPO_URL>` with actual values. | |
| Save to `artifacts/release-notes/generate_<version>.py`: | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/.claude/commands/generate.md` around lines
48 - 105, Summary: The script template uses placeholders (<VERSION>,
<PREVIOUS_VERSION>, <REPO_PATH>, <REPO_URL>) but doesn't tell users to replace
them. Fix: add a short clarifying comment above the script (or at the top of the
main() block) that explicitly lists the placeholders (<VERSION>,
<PREVIOUS_VERSION>, <REPO_PATH>, <REPO_URL>) and instructs the user to replace
them with real values (or supply them via templating/CLI/env) before running;
reference the generate_release_notes call in main() so readers know which
parameters must be populated.
Comment on lines
+107
to
+111
| ### 5. Execute | ||
|
|
||
| ```bash | ||
| cd artifacts/release-notes && python3 generate_<version>.py | ||
| ``` |
Contributor
There was a problem hiding this comment.
Path inconsistency between script and execution.
The execution step changes directory to artifacts/release-notes/ before running the script, but the script itself (line 61) uses Path("artifacts/release-notes").mkdir(...) which is a relative path. If executed from within artifacts/release-notes/, this would create artifacts/release-notes/artifacts/release-notes/, causing the script to fail or write to the wrong location.
🔧 Proposed fix
Either execute from the repository root:
-### 5. Execute
-
-```bash
-cd artifacts/release-notes && python3 generate_<version>.py
-```
+### 5. Execute
+
+```bash
+python3 artifacts/release-notes/generate_<version>.py
+```Or update the script to use absolute paths or adjust for the current directory.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ### 5. Execute | |
| ```bash | |
| cd artifacts/release-notes && python3 generate_<version>.py | |
| ``` | |
| ### 5. Execute | |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/.claude/commands/generate.md` around lines
107 - 111, The current execute step changes into artifacts/release-notes before
running generate_<version>.py, but the script itself calls
Path("artifacts/release-notes").mkdir(...) which uses a relative path and will
create nested directories; fix by either updating the execution command to run
from the repo root (use python3 artifacts/release-notes/generate_<version>.py in
the "Execute" section) or modify the script generate_<version>.py to build an
absolute path for the artifacts directory (use
Path(__file__).resolve().parent.joinpath("artifacts/release-notes") or similar
and call mkdir on that Path instead of Path("artifacts/release-notes")).
Comment on lines
+12
to
+25
| ```bash | ||
| cd /workspace/artifacts/release-notes-workflow | ||
|
|
||
| # Initialize git if needed | ||
| git init | ||
|
|
||
| # Or copy to your workflows repo | ||
| cp -r . /path/to/workflows-repo/workflows/release-notes-generator/ | ||
|
|
||
| cd /path/to/workflows-repo | ||
| git add workflows/release-notes-generator | ||
| git commit -m "feat: Add release notes generator workflow" | ||
| git push origin main # or your feature branch | ||
| ``` |
Contributor
There was a problem hiding this comment.
Path inconsistency in deployment instructions.
Line 13 references /workspace/artifacts/release-notes-workflow without establishing where this directory comes from or how users should get there. Then line 19 copies from the current directory (.) which contradicts the earlier path reference. This creates confusion about where the workflow files are located.
🔧 Suggested clarification
2. **Push this workflow**:
```bash
- cd /workspace/artifacts/release-notes-workflow
+ # Navigate to where you created/stored the workflow files
+ cd /path/to/your/release-notes-generator
# Initialize git if needed
git initOr provide a clearer explanation of where /workspace/artifacts/release-notes-workflow comes from in the workflow creation process.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ```bash | |
| cd /workspace/artifacts/release-notes-workflow | |
| # Initialize git if needed | |
| git init | |
| # Or copy to your workflows repo | |
| cp -r . /path/to/workflows-repo/workflows/release-notes-generator/ | |
| cd /path/to/workflows-repo | |
| git add workflows/release-notes-generator | |
| git commit -m "feat: Add release notes generator workflow" | |
| git push origin main # or your feature branch | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 12-12: Fenced code blocks should be surrounded by blank lines
(MD031, blanks-around-fences)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/DEPLOYMENT.md` around lines 12 - 25, Update
the deployment snippet to remove the ambiguous hard-coded path and make the
source and destination consistent: replace the reference to
"/workspace/artifacts/release-notes-workflow" with a placeholder or explanatory
comment like "cd /path/to/your/release-notes-generator" and ensure the
subsequent copy command ("cp -r .
/path/to/workflows-repo/workflows/release-notes-generator/") clearly matches
that same source location; also add one short line explaining how users obtain
or generate the workflow files if they aren't already present so both the cd and
cp commands are unambiguous.
Comment on lines
+151
to
+157
| ### Tool installation fails | ||
|
|
||
| **Check**: | ||
| - Python 3.12+ is available in ACP session | ||
| - pip works and has internet access | ||
| - Package name is correct: `utility-mcp-server` | ||
|
|
Contributor
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
What is the minimum Python version required for the utility-mcp-server package?
💡 Result:
The minimum Python version required by utility-mcp-server is Python 3.12 (it specifies Requires-Python: >=3.12, <3.14). [1]
🏁 Script executed:
cat -n workflows/release-notes-generator/DEPLOYMENT.mdRepository: ambient-code/workflows
Length of output: 8464
Python 3.12+ requirement should be documented earlier, not just in troubleshooting.
The Python 3.12+ version requirement appears only in the troubleshooting section (line 154), but users attempting deployment from the Quick Start or Verification Checklist will encounter it without prior notice. Add a Prerequisites section near the top of the guide listing Python 3.12+ as a requirement, or reference it explicitly in the Verification Checklist (line 106).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/DEPLOYMENT.md` around lines 151 - 157, The
docs currently only mention Python 3.12+ under the "Tool installation fails"
troubleshooting section; add a "Prerequisites" section near the top (before
Quick Start) that explicitly lists Python 3.12+ (and pip/internet access) or
alternately update the "Verification Checklist" heading to call out "Requires
Python 3.12+" so users see the requirement earlier; update headings referenced
("Quick Start", "Verification Checklist", and "Tool installation fails") to
ensure consistency and add a short note about verifying python --version.
Comment on lines
+6
to
+14
| # Move the temp file to the correct location | ||
| if [ -f "generate_command_temp.md" ]; then | ||
| mv generate_command_temp.md .claude/commands/generate.md | ||
| echo "✅ Successfully installed /generate command at .claude/commands/generate.md" | ||
| else | ||
| echo "❌ Error: generate_command_temp.md not found" | ||
| echo "Make sure you're running this from the workflow directory" | ||
| exit 1 | ||
| fi |
Contributor
There was a problem hiding this comment.
Create target directory before moving the file.
The script attempts to move generate_command_temp.md to .claude/commands/generate.md without first ensuring the .claude/commands/ directory exists. This will cause the mv command to fail if the directory structure hasn't been created yet.
📁 Proposed fix to create directory structure
# Move the temp file to the correct location
if [ -f "generate_command_temp.md" ]; then
+ mkdir -p .claude/commands
mv generate_command_temp.md .claude/commands/generate.md
echo "✅ Successfully installed /generate command at .claude/commands/generate.md"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| # Move the temp file to the correct location | |
| if [ -f "generate_command_temp.md" ]; then | |
| mv generate_command_temp.md .claude/commands/generate.md | |
| echo "✅ Successfully installed /generate command at .claude/commands/generate.md" | |
| else | |
| echo "❌ Error: generate_command_temp.md not found" | |
| echo "Make sure you're running this from the workflow directory" | |
| exit 1 | |
| fi | |
| # Move the temp file to the correct location | |
| if [ -f "generate_command_temp.md" ]; then | |
| mkdir -p .claude/commands | |
| mv generate_command_temp.md .claude/commands/generate.md | |
| echo "✅ Successfully installed /generate command at .claude/commands/generate.md" | |
| else | |
| echo "❌ Error: generate_command_temp.md not found" | |
| echo "Make sure you're running this from the workflow directory" | |
| exit 1 | |
| fi |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/release-notes-generator/install-command.sh` around lines 6 - 14,
The install script moves generate_command_temp.md to
.claude/commands/generate.md but doesn't ensure the target directory exists;
before calling mv (the block that handles generate_command_temp.md and
.claude/commands/generate.md), create the directory with a safe recursive mkdir
(e.g., mkdir -p .claude/commands) and handle any mkdir failures so the
subsequent mv succeeds and the existing echo/exit handling remains correct.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new workflow for generating structured release notes from git commits and tags with automatic categorization.
Features
/generatecommandTechnical Details
utility-mcp-serverPython package for git analysisartifacts/release-notes/Workflow Structure
Testing
Tested extensively in ACP with Custom Workflow:
/generatecommand functions correctlyartifacts/release-notes/Use Cases
Perfect for:
Example Output
Why This Workflow?
Release notes are critical for communicating changes to users, but manually creating them is time-consuming and error-prone. This workflow automates the process while maintaining high quality and consistency.
The workflow intelligently parses commit messages, extracts meaningful information, and presents it in a professional format that's ready to publish.
Ready for Review
This workflow has been thoroughly tested and is production-ready. It follows all ACP workflow conventions and includes comprehensive documentation for users.
Looking forward to feedback and making this available to the ACP community! 🚀