SfSkills Domains Docs GitHub

Home / devops / release-notes-automation

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. NOT for managed-package version creation, push upgrades, or org assessment — use admin/salesforce-release-preparation.

Open the skill folder on GitHub

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:

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

SituationRecommended ApproachReason
Brand-new repo, no convention yetConventional Commits + commitlint pre-commit hookCheapest discipline; pipeline is generic
Established repo with Jira keys in commitsJira-keyed grouping with cachingExisting data; no commit-flow churn
Mixed audience (dev + stakeholders)Generate two outputs from the same runDevs see commits; PMs see Jira summaries
Hotfix release off a previous tagManual from-ref override inputAuto-resolution of previous tag picks the wrong base
  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

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

ArtifactDescription
RELEASE_NOTES.mdThe grouped, audience-targeted Markdown
metadata-diff.mdPer-type list of changed metadata source paths
GitHub/Bitbucket ReleaseThe hosted artifact, tagged at to-ref

Package files