| name | connect-web-release-notes |
| description | Generates Markdown release notes for the latest commcare-connect release and posts them to Confluence and Slack. Use when the user asks for Connect release notes, a changelog, or what changed in the last release (no repo URL needed).
|
Connect Release Notes
Generate release notes for the most recent release of dimagi/commcare-connect. Run
end-to-end automatically — no input is required from the user.
Terminology
Use user-facing product terms, not internal code names:
| Use this | Not this |
|---|
| PersonalID | ConnectID |
If a PR title or body uses an internal model name, database field, or code identifier
as if it were a product concept, rephrase it into plain language.
Step 1: Find the releases
gh release list --repo dimagi/commcare-connect --limit 5
Identify the latest release and the previous release. Note both tag names and
published dates (you need both to bound the PR search).
Step 2: Find merged PRs between the releases
gh pr list \
--repo dimagi/commcare-connect \
--state merged \
--search "merged:PREV_DATE..LATEST_DATE" \
--json number,title,author,mergedAt,labels \
--limit 100
Use YYYY-MM-DD format for both dates.
Step 3: Fetch PR details
For each PR, fetch the title and body:
gh pr view <number> --repo dimagi/commcare-connect --json title,body,labels
Batch these in parallel — fetch several per message to avoid unnecessary round-trips.
Focus on the Product Description section of each body — that's where the user-facing
impact is described.
Handling reverts: If a PR title starts with "Revert" and references another PR,
exclude both that revert PR and the original PR it reverts. Their net effect on the
codebase is zero, so they don't belong in release notes.
Step 4: Categorize each PR
Assign each PR to exactly one of:
- New — a brand-new feature or capability that didn't exist before
- Improvements — an enhancement, refinement, or extension of something existing;
also includes new API capabilities that extend existing endpoints
- Bug Fixes — a correction to broken or incorrect behavior
Skip entirely (don't include in any section):
- Purely internal refactors: model/field renames with no user-facing effect
- Unreleased feature removals (waffle switches never rolled out)
- Feature flag / waffle switch cleanup for already-released features
- Dependency bumps, CI config changes, version pin updates
Don't skip just because a PR has no Product Description section. Some PRs (e.g.
new third-party integrations, infrastructure additions) only have a Technical Summary.
If the PR introduces something that affects users or operators — a new integration,
a new configuration option, a new service — include it. Use the PR title and
Technical Summary to write the description.
Step 5: Write the release notes
Group everything into exactly three top-level sections — no feature-area subsections.
Within each section, order items from most impactful / most user-visible to least.
# Release Notes — Connect v{version}
*Released {date}*
---
## New
**Feature Title** — One to two sentences written for a non-technical stakeholder.
What does the user now see or can now do? [Screenshots](PR_URL)
...
---
## Improvements
**Feature Title** — Description. [Demo](PR_URL)
...
---
## Bug Fixes
**Feature Title** — Description of what was broken and what the fix does.
...
Title: Short noun phrase — rephrase the raw PR title if it reads like a commit
message or ticket reference. The title should describe the thing, not the action
(e.g. "Work Area CSV Export", not "Add CSV export for work areas").
Description: One to two sentences. What does the user now see or experience?
Avoid implementation details. Omit a section entirely if it has no items.
Links: Add [Screenshots](PR_URL) if the PR body contains screenshots,
[Demo](PR_URL) if it contains a video or GIF. Don't add links otherwise.
Step 6: Save the output
mkdir -p ./outputs
Save to ./outputs/release_notes_{version}.md.
Step 7: Post to Confluence
Post the release notes to the top of the Web Release Notes page:
Page ID: 3870556169
Cloud ID: dimagi.atlassian.net
First fetch the current page content so you know what's already there. Then update
the page with the new release notes prepended above any existing content, separated
by a horizontal rule (---).
Include the GitHub PR links ([Screenshots](PR_URL) / [Demo](PR_URL)) in the
Confluence version — don't strip them.
Use "Add v{version} release notes" as the version message.
Tell the user the file path where the notes were saved and confirm the Confluence
page was updated with a link to it.
Step 8: Post to Slack
Post the release notes to the Connect release notes Slack channel:
Channel: #connect-product-feed (channel ID: C08MRUZ8T9A)
Use the Slack MCP slack_send_message tool. Format the message using Slack's mrkdwn
syntax — not standard Markdown:
- Opening line:
**Connect v{version}** — Released {date} (no emojis)
- Section headers:
**NEW**, **IMPROVEMENTS**, **BUG FIXES** (bold all-caps, no ##)
- Bullet items:
• Feature Title — Description. <PR_URL|Screenshots> or <PR_URL|Demo>
- Feature title is plain text; only section headers are bold
- Use
**double asterisks** for bold — the tool uses standard Markdown where *single* renders as italic
- Links:
<url|label> syntax (not [label](url))
- Do not use
--- horizontal rules — they are invalid in Slack messages
- Do not use emojis anywhere in the message
- Keep bullet descriptions concise (one sentence); the full notes are on Confluence
- End with a plain link to the Confluence page:
Full release notes: <https://dimagi.atlassian.net/wiki/spaces/connectpublic/pages/3870556169/Web+Release+Notes|Web Release Notes on Confluence>
Confirm to the user that the Slack message was posted and include the message link.
