release-notes-automation
Use when generating customer- or stakeholder-facing release notes from git history, Jira/ADO ticket links, and Salesforce metadata diffs at deploy time. Triggers: 'auto-generate release notes', 'changelog from commits', 'release notes from PR titles', 'what changed in this deployment'. NOT for managed-package version creation, push upgrades, or org assessment.
Best use case
release-notes-automation is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Use when generating customer- or stakeholder-facing release notes from git history, Jira/ADO ticket links, and Salesforce metadata diffs at deploy time. Triggers: 'auto-generate release notes', 'changelog from commits', 'release notes from PR titles', 'what changed in this deployment'. NOT for managed-package version creation, push upgrades, or org assessment.
Teams using release-notes-automation should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/release-notes-automation/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How release-notes-automation Compares
| Feature / Agent | release-notes-automation | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Use when generating customer- or stakeholder-facing release notes from git history, Jira/ADO ticket links, and Salesforce metadata diffs at deploy time. Triggers: 'auto-generate release notes', 'changelog from commits', 'release notes from PR titles', 'what changed in this deployment'. NOT for managed-package version creation, push upgrades, or org assessment.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Release Notes Automation
Activate when an engineering team is shipping Salesforce work on a regular cadence (weekly, monthly, per-sprint) and the release notes are still being hand-written. The skill produces a deterministic pipeline that turns the git diff between two refs plus linked tickets into stakeholder-facing notes, attaches the metadata diff, and posts the result to the release tracking surface.
---
## Before Starting
Gather this context before working on anything in this domain:
- The repo's commit-message convention (Conventional Commits, "JIRA-1234: Title", PR-squashed, freeform). Without a convention, the pipeline can only group by file path or PR title — both noisier than ticket-keyed grouping.
- Whether the team uses GitHub Releases, Bitbucket Tags, Azure DevOps Releases, or a wiki page. The output shape needs to match.
- Who reads the notes. A "developer changelog" lists every PR; a "stakeholder release note" hides infra commits and groups by feature. Often you need both, generated from the same source.
---
## Core Concepts
### Range of changes
Release notes always span `from-ref...to-ref`. The pipeline must resolve `from-ref` deterministically — usually the previous git tag matching a release pattern (e.g., `v*`). `git describe --tags --abbrev=0 --match 'v*' to-ref^` is the canonical resolver. Fallbacks include "first commit" for the initial release and a manually overridden previous-ref for hotfix branches.
### Categorization
Conventional Commits give the pipeline `feat:`, `fix:`, `chore:`, `refactor:` prefixes — the cheapest possible grouping. Where the team uses Jira keys instead, fetch issue type from the tracker and map to Added/Fixed/Changed/Deprecated/Removed/Security (Keep a Changelog convention). PR labels are the third option, useful when the merge-commit subject is squashed.
### Metadata diff
For Salesforce-specific notes, the package-level diff matters: which Apex classes, LWCs, Flows, custom objects, and permission sets changed. `sf project deploy preview` or a `git diff --name-only` filtered to `force-app/main/default/...` gives a metadata-aware section that complements the human-readable Jira summary.
---
## Common Patterns
### Pattern: Conventional Commits + git tag pipeline
**When to use:** Team disciplines commits with `feat:`/`fix:`/etc.
**How it works:** GitHub Action triggered on tag push. Resolves previous tag, runs `git log` between tags, groups by Conventional Commits prefix, posts a GitHub Release with the grouped Markdown.
**Why not the alternative:** Hand-typing release notes from `git log` output is reliable for releases 1–3 and degrades fast.
### Pattern: Jira-keyed grouping
**When to use:** Commit messages contain `ABC-1234` keys but no convention prefix.
**How it works:** Pipeline parses Jira keys from each commit subject, calls Jira's `/rest/api/3/issue/{key}` once per unique key (with caching), groups by issue type (Story/Bug/Task), and emits the title from Jira plus a link.
### Pattern: Salesforce metadata-diff section
**When to use:** Product manager wants to know "did Apex change in this release?"
**How it works:** Append a section listing changed `force-app/main/default/<type>/<name>` paths grouped by metadata type, derived from `git diff --name-status from-ref to-ref -- force-app/`.
---
## Decision Guidance
| Situation | Recommended Approach | Reason |
|---|---|---|
| Brand-new repo, no convention yet | Conventional Commits + commitlint pre-commit hook | Cheapest discipline; pipeline is generic |
| Established repo with Jira keys in commits | Jira-keyed grouping with caching | Existing data; no commit-flow churn |
| Mixed audience (dev + stakeholders) | Generate two outputs from the same run | Devs see commits; PMs see Jira summaries |
| Hotfix release off a previous tag | Manual `from-ref` override input | Auto-resolution of previous tag picks the wrong base |
---
## Recommended Workflow
1. Confirm the commit/PR convention. If absent, propose adopting one before automating.
2. Decide the trigger: tag push, manual workflow dispatch, or the deployment-promotion pipeline. Tag push is simplest; deployment-promotion ties notes to the actual production change.
3. Implement the from-ref resolver. Use `git describe --tags --abbrev=0 --match '<release-tag-pattern>' <to-ref>^`. Add a fallback for the initial release.
4. Implement the grouping. Conventional Commits is regex; Jira-keyed needs API token storage in the pipeline secret manager (see `devops/pipeline-secrets-management`).
5. Append the Salesforce metadata-diff section using `git diff --name-status from-ref to-ref -- force-app/`. Group by `<type>/<name>`.
6. Render Markdown and post to GitHub Release / Bitbucket Tag / wiki. Store the artifact alongside the release tag for audit.
7. Validate the output on a real release before declaring done. Hand-review the first three runs; tune category mappings.
---
## Review Checklist
- [ ] `from-ref` resolution is deterministic and survives hotfix branches
- [ ] Output is reproducible — re-running on the same range yields byte-identical Markdown
- [ ] Jira/ADO API tokens are stored in the secret manager, not the workflow YAML
- [ ] Salesforce metadata-diff section grouped by metadata type
- [ ] Two output flavors (dev / stakeholder) wired if both audiences exist
- [ ] Failed pipeline does not silently drop notes — tag push without notes is alerted
---
## Salesforce-Specific Gotchas
1. **Squashed PR commits lose individual ticket keys** — Whatever the merge-commit subject contains is the only data the pipeline sees. Discipline merge subjects, or read PR descriptions via the Git host API.
2. **Metadata-diff on `force-app/` misses `manifest/package.xml` changes** — Adding a new metadata type via package.xml without source files (rare but real) shows up as zero source-file changes. Diff `manifest/package.xml` separately if you generate it.
3. **Tag pattern collisions** — `git describe --match 'v*'` matches `v1.0.0` and a stray `version-x` tag from a contributor. Pin the pattern (`v[0-9]*`) precisely.
---
## Output Artifacts
| Artifact | Description |
|---|---|
| RELEASE_NOTES.md | The grouped, audience-targeted Markdown |
| metadata-diff.md | Per-type list of changed metadata source paths |
| GitHub/Bitbucket Release | The hosted artifact, tagged at `to-ref` |
---
## Related Skills
- devops/git-branching-for-salesforce — branching model determines what `from-ref` and `to-ref` mean
- devops/pipeline-secrets-management — for storing Jira/ADO tokens used by the categorizer
- devops/managed-package-development — when the deliverable is a package version, the version's release notes feed the same artifactRelated Skills
salesforce-cli-automation
Use this skill when automating Salesforce work with the unified Salesforce CLI (`sf`, v2): shell scripts, Make/npm tasks, cron jobs, and CI steps that need stable flags, `--json` output, org aliases, bulk/data commands, plugins, and non-interactive auth patterns. Trigger keywords: sf CLI automation, sfdx migration, JSON output CI, sf project deploy script, sf data bulk, CLI plugins, target-org alias, machine-readable CLI. NOT for choosing or wiring a specific CI platform (GitHub Actions, GitLab, Jenkins, Bitbucket, Azure DevOps—use those devops skills), VS Code Salesforce extensions, or Copado/Gearset release management UIs.
release-management
Use when planning, coordinating, or governing Salesforce releases: version numbering, rollback strategy, release notes, go/no-go criteria, release calendar, and sandbox preview alignment. NOT for deployment mechanics (use devops/post-deployment-validation or devops/change-set-deployment).
cumulusci-automation
Use this skill when configuring CumulusCI (cci) for Salesforce project automation: authoring cumulusci.yml tasks and flows, customizing or composing standard flows, integrating Robot Framework acceptance tests, and running cci flows in CI pipelines with JWT-based authentication. Covers task class_path/options wiring, flow step ordering, org and source declarations, cross-project reuse via sources, and the standard flow library (dev_org, qa_org, ci_feature, install_beta). NOT for raw SFDX/sf CLI workflows without CumulusCI, scratch org pool management (use scratch-org-pools), unlocked or managed package versioning (use unlocked-package-development or second-generation-managed-packages), or Salesforce-native DevOps Center pipelines (use devops-center-pipeline).
deployment-automation-architecture
Deployment automation architecture on Salesforce: pipeline orchestration, branch strategy, environment topology, quality gates, release trains. Selecting between Copado, Gearset, Flosum, and native SFDX + GitHub Actions. NOT for cloud-specific deploy mechanics (use cloud-specific-deployment-architecture). NOT for CI/CD tool tutorials.
cpq-test-automation
Use when writing, reviewing, or debugging test classes for Salesforce CPQ (Steelbrick) functionality — including quote creation, price rules, contracting, ordering, and CPQ API integration. Trigger keywords: CPQ test class, SBQQ test, quote calculation test, price rule test, CPQ Apex test, ServiceRouter test, QuoteCalculator test. NOT for standard Apex testing patterns unrelated to CPQ, nor for UI/Selenium test authoring outside the CPQ context.
cpq-api-and-automation
Use when programmatically driving Salesforce CPQ operations from Apex or REST — creating quotes, adding products, calculating pricing, saving quotes, amending contracts, or renewing contracts through the SBQQ.ServiceRouter API. Trigger keywords: CPQ API, SBQQ.ServiceRouter, QuoteCalculator, QuoteReader, QuoteSaver, QuoteProductAdder, ProductLoader, ContractAmender, ContractRenewer, programmatic quote, calculate callback, CPQ REST API. NOT for standard REST API or Salesforce Connect. NOT for declarative CPQ configuration such as price rules, discount schedules, or product rules. NOT for CPQ plugin interfaces (QuoteCalculatorPlugin, OrderPlugin).
sandbox-post-refresh-automation
Automating the post-sandbox-refresh cleanup via the `SandboxPostCopy` interface — the Apex class that runs ONCE after a sandbox refresh / clone completes, before users can log in. Used to mask emails, deactivate users, scrub integration endpoints, disable scheduled jobs, repopulate sample data, and reapply any per-environment configuration that the metadata copy doesn't carry. Covers the interface contract (`runApexClass` setting, `SandboxContext` parameter, single-execution semantics), the email-masking pattern that prevents production emails firing from sandbox tests, and the runbook checklist of what every refresh should reset. NOT for the sandbox refresh-strategy decision (use devops/sandbox-strategy-designer), NOT for general bulk Apex (use apex/scheduled-apex).
salesforce-release-preparation
Use when preparing for a Salesforce seasonal release — triaging release notes, reviewing Release Updates, opting into Sandbox Preview, and communicating change impact to stakeholders. Triggers: 'upcoming Salesforce release', 'release notes triage', 'Release Updates', 'sandbox preview opt-in', 'release readiness checklist', 'production upgrade date', 'feature impact', 'critical update'. NOT for deploying org-specific changes between sandboxes (use change-management-and-deployment), nor for long-term sandbox environment design (use sandbox-strategy).
process-automation-selection
Use when deciding which Salesforce automation tool should own a requirement, including before-save and after-save Flow, screen Flow, scheduled Flow, invocable Apex, Apex triggers, and migration off Workflow Rules or Process Builder. Triggers: 'Flow or Apex trigger', 'which automation tool should I use', 'Process Builder migration', 'Workflow Rule retirement', 'same-record update or trigger'. NOT for detailed implementation of a Flow or trigger after the automation boundary has already been chosen.
marketing-automation-requirements
Use this skill when gathering, documenting, or validating requirements for a Salesforce marketing automation program — covering MCAE (Account Engagement / Pardot) lifecycle stages, MQL/SQL threshold definitions, scoring model specifications (sources, weights, decay, ceiling), handoff notification design, CRM field updates on status change, and sales SLA. Trigger keywords: MQL criteria, marketing-to-sales handoff, lead lifecycle, scoring requirements, automation program requirements, Marketing Cloud Automation Studio scope. NOT for implementation of MCAE automation rules, MCAE scoring configuration, MC Automation Studio SQL activity authoring, or Einstein Lead Scoring setup — those are covered by dedicated implementation skills.
xss-and-injection-prevention
Use when writing or reviewing Visualforce pages, Apex controllers, or LWC components that output user-supplied data, build dynamic queries, or construct HTTP responses. Triggers: 'XSS in Visualforce', 'SOQL injection vulnerability', 'how to encode output in Apex', 'JSENCODE Visualforce', 'open redirect prevention'. NOT for Apex CRUD/FLS enforcement (use soql-security or apex-crud-and-fls), NOT for Shield encryption (use shield-encryption-key-management), NOT for AppExchange security review process (use secure-coding-review-checklist).
visualforce-security-and-modernization
Use when hardening or modernizing legacy Visualforce pages — covers the platform CSRF token model and when disabling it is a security regression, view state encryption guarantees and the 170 KB ceiling, FLS/CRUD enforcement gaps on `<apex:outputField>` and on getters that return sObjects, `<apex:includeScript>` interaction with the org Content Security Policy, hosting LWC inside a VF page via `lightning:container` / `lightning-out`, and the retire-vs-harden-vs-leave-alone decision for an inventory of legacy pages. Triggers: 'should I rewrite this Visualforce page in LWC', 'CSRF protection disabled on Visualforce page is that safe', 'community user sees a field they should not on a Visualforce page', 'view state encryption is that enough for sensitive data', 'how do I host an LWC inside a Visualforce page', 'apex:dynamicComponent and apex:actionFunction safe to keep'. NOT for greenfield Visualforce architecture (use apex/visualforce-fundamentals — controller types, view state pattern selection, PDF rendering); NOT for Visualforce email template authoring (use apex/visualforce-email-templates if/when that skill is authored); NOT for general Apex security review across triggers and async (use apex/soql-security and security/secure-coding-review-checklist).