Release Notes Automation

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

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

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 artifact