agentleFS
forcedotcomforcedotcom/salesforcedx-vscode/.claude/skills/changelog/SKILL.md

changelog

Skill1k starsChanged 28 days agoBSD-3-ClauseView on GitHub

Polish the automated CHANGELOG on develop before the next stable build. Removes GUS refs, categorizes under-the-cover changes, improves customer-facing descriptions. Use when preparing/reviewing the changelog after a weekly prerelease promotion, or when user mentions changelog quality.

  • Commits and pushes

165 other projects use a version of this.

Adopted by

Steady: 0 new projects took it in the last 4 weeks, none the 4 weeks before.thin data

Week of Sep 20: 0 new projectsWeek of Sep 27: 0 new projectsWeek of Oct 4: 0 new projectsWeek of Oct 11: 0 new projectsWeek of Oct 18: 0 new projectsWeek of Oct 25: 0 new projectsWeek of Nov 1: 0 new projectsWeek of Nov 8: 0 new projects
Sep 2026Oct 2026Nov 2026
New projects taking a version of this file each week, over the 8 weeks our latest run read: only 0 in all, so this is a hint, not a trend.

Most recently taken up by

Who's talking about forcedotcom/salesforcedx-vscode

The biggest 5 of 52 mentions linking to the repository that our crawl found. Each line is their own headline.

See all 52

Talked about on GitHub and Stack Overflow (52 times).

On GitHub · 50

45 more on GitHub

Used with

Projects with it also use playtest-report, soak-test and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • CoralGameSkill

    playtest-report

    Generates a structured playtest report template or analyzes existing playtest notes into a structured format. Use this to standardize playtest feedback collection and analysis.

    Also in 12 projects that use this

  • lilangMaxSkill

    soak-test

    Generate a soak test protocol for extended play sessions. Defines what to observe, measure, and log during long play sessions to surface slow leaks, fatigue effects, and edge cases that only appear after sustained play. Primarily used in Polish and Release phases.

    Also in 9 projects that use this

  • lilangMaxSkill

    team-live-ops

    Orchestrate the live-ops team for post-launch content planning: coordinates live-ops-designer, economy-designer, analytics-engineer, community-manager, writer, and narrative-director to design and plan a season, event, or live content update.

    Also in 9 projects that use this

  • CoralGameSkill

    team-polish

    Orchestrate the polish team: coordinates performance-analyst, technical-artist, sound-designer, and qa-tester to optimize, polish, and harden a feature or area for release quality.

    Also in 14 projects that use this

  • +5 more from lilangMax
  • +3 more from CoralGame

The file

Show its rules and text

We split this skill into the rules it gives an agent

18 rules. 0 are common, 9 are distinctive, and 9 are very specific to this project.

  • 0

    Common

    Most of the 154 edited versions we read keep these.

  • 9

    Distinctive

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Test infrastructure (E2E suites, unit tests, test utilities)

    line 43
  2. Very specific:

    Use PR commits, title, body, and labels to decide.

    line 56
  3. Distinctive:

    Write from the user's perspective: "We added...", "We fixed...", "You can now..."

    line 67
  4. Very specific:

    Start with We added…, We fixed a bug where…, We improved…, We reverted…, or The <X> now….

    line 69
  5. Distinctive:

    Keep entries to 1-2 sentences max

    line 72
  6. Very specific:

    Prefer VS Code over VSCode.

    line 77
  7. Distinctive:

    After the PR link(s), append issue and discussion links found in the "What issues does this PR fix or reference?" section of the PR body:

    line 78
  8. Distinctive:

    Only include issues/discussions explicitly listed in that section.

    line 82
  9. Distinctive:

    Remove empty package sections (header with no entries)

    line 90
  10. Distinctive:

    After user approves the polished changelog:

    line 124
  11. Very specific:

    Make sure you're on develop and up to date: git checkout develop && git pull

    line 126
  12. Very specific:

    Verify no other files are staged: git diff --cached --name-only must show only packages/salesforcedx-vscode/CHANGELOG.md.

    line 128
  13. Distinctive:

    Never include other file changes in this commit.

    line 132
  14. Very specific:

    Use these chore: subjects for polish commits on develop:

    line 134
  15. Very specific:

    If salesforcedx-vscode-core is touched, all other touched packages (except docs) are dropped for that commit

    line 200
  16. Very specific:

    If salesforcedx-vscode-services is touched alongside exactly one other (non-docs) package, salesforcedx-vscode-services is dropped and the …

    line 201
  17. Very specific:

    Only packages starting with salesforce or docs count.

    line 202
  18. Distinctive:

    No dedupe against the existing changelog file — the range is disjoint by construction (see Commit details above)

    line 209

“Common” is measured: kept by at least 6 in 10 of the 154 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Changelog Polish

Improve the automated changelog delta committed to develop by promote-to-prerelease.yml.

Scope: polish at packages/salesforcedx-vscode/CHANGELOG.md (per-package CHANGELOG.md files scoped to their own packages, out of scope). Root CHANGELOG.md is auto-maintained: promote-to-prerelease.yml prepends each week's delta, then stable builds later fold those sections into one stable release section via fold-stable-changelog.js — do not edit root manually.

When to use

  • User invokes /changelog or asks to prepare/review the changelog
  • On develop, after a chore: changelog for prerelease vX.Y.Z commit lands
  • Timing matters: polish it before build-github-release.yml (Wednesdays, 7 AM UTC). Stable builds fold develop's root CHANGELOG.md and overlay polish from package CHANGELOG.md into the shipped release version, then bake into the VSIX. Once that's run, content is frozen in the artifact — fixing afterward requires manually re-injecting into the release's VSIX asset.

File location

packages/salesforcedx-vscode/CHANGELOG.md on develop

Workflow

  1. Checkout/pull develop and read the current changelog file
  2. Identify the automated commit: git log --oneline -- packages/salesforcedx-vscode/CHANGELOG.md | grep "changelog for prerelease"
  3. For each entry, fetch PR context: gh pr view <number> --json title,body,commits,labels. In the body, look for a "What issues does this PR fix or reference?" section and extract any issue or discussion numbers linked there.
  4. Apply the rules below to produce a polished draft
  5. Present the revised changelog to the user for approval before writing

Rules

1. Remove GUS work item references

Strip any W-NNNNNNN or - W-NNNNNNN text from entries. These are internal tracking IDs not meaningful to customers.

Before: - Add a Max Rows input to SOQL Builder UI - W-22199672 ([PR #7261](... After: - We added a **Max Rows** input to SOQL Builder UI so you can limit the number of rows retrieved. ([PR #7261](...

2. Classify entries as customer-facing or under-the-cover

Under-the-cover (not visible to users):

  • Test infrastructure (E2E suites, unit tests, test utilities)
  • Internal telemetry/observability (span attributes, logging)
  • Refactoring with no behavior change
  • CI/CD pipeline changes
  • Dependency bumps with no user-visible effect
  • Internal API changes between packages

Customer-facing (visible to users):

  • New commands, UI elements, or features
  • Bug fixes that affected user workflows
  • Performance improvements users would notice
  • Behavior changes in existing features

Use PR commits, title, body, and labels to decide. When uncertain, check the diff: gh pr diff <number> --name-only to see which files changed.

Under-the-cover entries go under a dedicated ## Under the Hood section (no package sub-headers needed). Consolidate all under-the-cover PRs into one or a few lines: - We made some under the hood changes. ([PR #NNNN](...), [PR #MMMM](...)).

3. Deduplicate multi-package entries

The automation lists the same PR under every package it touched. Consolidate to the most relevant user-facing package. If a change touched salesforcedx-vscode-services plus a feature extension, list it under the feature extension only.

4. Improve customer-facing descriptions

  • Write from the user's perspective: "We added...", "We fixed...", "You can now..."
  • Describe what the user can do or what changed for them, not the implementation
  • Start with We added…, We fixed a bug where…, We improved…, We reverted…, or The <X> now…. Full sentences ending in .
  • Bold user-facing names: extensions (Salesforce Metadata Visualizer), commands (SFDX: Create Project), UI elements (Run button, Org Differences view, Ready for Review)
  • Backticks for code identifiers, file names, config keys: jsconfig.json, sourceApiVersion, MetadataRegistryService, .soql
  • Keep entries to 1-2 sentences max
  • For opaque/internal fixes where customer impact is unclear: We made some changes under the hood.
  • For reverts: We reverted <X> because <reason>.
  • For setting/option additions: name the setting in bold, describe default behavior
  • For extension-pack additions: include extension id in parens, e.g. **Salesforce Live Preview** (salesforce.salesforcedx-vscode-ui-preview)
  • Prefer VS Code over VSCode; on Windows not in Windows
  • After the PR link(s), append issue and discussion links found in the "What issues does this PR fix or reference?" section of the PR body:
    • Issues: [ISSUE #NNNN](https://github.com/forcedotcom/salesforcedx-vscode/issues/NNNN)
    • Discussions: [DISCUSSION #NNNN](https://github.com/forcedotcom/salesforcedx-vscode/discussions/NNNN)
    • Format: ([PR #7517](...), [ISSUE #4065](...))
    • Only include issues/discussions explicitly listed in that section; do not infer from commit messages or other body text

5. Verify categories

  • ## Added — new features, new commands, new UI
  • ## Fixed — bug fixes
  • ## Changed — behavior changes to existing features (add section if needed)
  • ## Under the Hood — internal changes not visible to users (CI, telemetry, refactoring, dep bumps). No package sub-headers needed.
  • Remove empty package sections (header with no entries)

Example transformation

Automated:

## Added

#### salesforcedx-vscode-metadata

- Filter packageDirs to those containing target folder - W-22049669 ([PR #7225](...))

#### salesforcedx-vscode-services

- Filter packageDirs to those containing target folder - W-22049669 ([PR #7225](...))

- Replace static activationEvents with programmatic activation W-21956120 ([PR #7154](...))

Polished:

## Added

#### salesforcedx-vscode-metadata

- When creating an Apex class or LWC component, the output directory picker now lists only package directories that contain the relevant folder. ([PR #7225](...))

## Under the Hood

- We made some under the hood changes. ([PR #7154](...))

Commit and push

After user approves the polished changelog:

  1. Make sure you're on develop and up to date: git checkout develop && git pull
  2. Stage only the changelog file: git add packages/salesforcedx-vscode/CHANGELOG.md
  3. Verify no other files are staged: git diff --cached --name-only must show only packages/salesforcedx-vscode/CHANGELOG.md. If other files appear, unstage them before committing.
  4. Commit: git commit -m "chore: polish changelog [skip ci]"
  5. Push: git push origin develop

Never include other file changes in this commit.

Use these chore: subjects for polish commits on develop:

  • chore: polish changelog
  • chore: write into sentences
  • chore: changelog improvements
  • chore: update changelog
  • chore: missing changelog entry
  • chore: clean up duplicate entries
  • chore: merge vX.Y.A and vX.Y.B changelogs (when prior patch's entries need to roll into current)

Reference: changelog lifecycle

promote-to-prerelease.yml runs 3-stage pipeline to generate & polish changelog before commit to develop. Background context; typically not interacted with during manual polish.

Compute → Polish (AI) → Commit → Review (human)

  1. compute-changelog-range (promote-to-prerelease.yml): Outputs fromRef = newest marketplace-prerelease-* tag (set by last week's promote run) or latest stable v* tag (correct fallback before any tracking tag exists). Empty fromRef (identical to this week's nightly commit — a manual re-run or hotfix) skips changelog-body instead of feeding it an identical range.
  2. changelog-body (reusable workflow .github/workflows/changelog-body.yml): Calls Cursor-backed AI (guided by .cursor/skills/changelog-judgment/SKILL.md) to produce polished, customer-facing markdown body from commits in range (fromRef, toRef]. Already removes GUS refs, rewrites sentences ("We added/fixed/improved..."), dedupes multi-package PRs, consolidates Under-the-Hood. Returns body output.
  3. write-changelog (promote-to-prerelease.yml): Writes header # <version> - <date> + body to packages/salesforcedx-vscode/CHANGELOG.md. Runs scripts/prepend-release-changelog.js to prepend same content to root CHANGELOG.md. Both labeled with prerelease version (e.g. 67.17.9). Committed to develop.
  4. Polish (optional) (develop, this skill): Human review/touch-up before next build-github-release.yml run. Model-generated body is typically ready, but catch edge cases/errors using Rules 1–5 as checklist. Note: polish edits to package CHANGELOG.md are picked up by the stable build (via --overlay); edits to root are not auto-synced (folding process replaces root sections).
  5. Fold to stable (build-github-release.yml, Wednesday 7 AM UTC): For stable builds (skips emergency pre-releases): pulls develop's root CHANGELOG.md, overlays package CHANGELOG.md polish from step 4, folds every prerelease section it contains into one stable section (fold-stable-changelog.js), bakes into stable VSIX (package CHANGELOG.md).
  6. Fold history (publishVSCode.yml, on final stable publish): For stable releases (skips pre-release tags): folds develop's root CHANGELOG.md, so history matches shipped stable version; commits only root CHANGELOG.md to develop (no longer touches package changelog).

prepend-release-changelog.js validates structure (version format, file existence, non-empty), runs idempotent (skips if already in root), reports errors (ENOSPC, EACCES, missing files). fold-stable-changelog.js (run by build-github-release.yml and publishVSCode.yml) is also idempotent: no-op if root already starts with the stable version (pre-prepared branches), or if no prerelease sections fold into it (hotfixes of stable releases).

Commit details

  • Commit: chore: changelog for prerelease vXX.YY.ZZ [skip ci]
  • Range: previous week's promoted prerelease to nightly SHA (disjoint by construction — changelog-body doesn't read the existing file, so there's nothing to dedupe against)
  • Skipped if changelog-body returns an empty body (no feat/fix/perf commits in range)

Format

# XX.YY.ZZ - Month DD, YYYY

## Added

#### <package-name>

- <message> ([PR #<num>](https://github.com/forcedotcom/salesforcedx-vscode/pull/<num>))

## Fixed

#### <package-name>

- <message> ([PR #<num>](...))

## Under the Hood

- We made some under the hood changes. ([PR #<num>](...), [PR #<num>](...))
  • Top header: # <version> - <release date>; date is +7 days from this Wednesday's prerelease (next Wednesday's stable release), written by the write-changelog job, not changelog-body
  • Sections, in order: Added, Fixed, Changed, Under the Hood. Section is an AI judgment call per .cursor/skills/changelog-judgment/SKILL.md (Added = new capability, Fixed = bugfix, Changed = behavior change, Under the Hood = invisible to users), not a fixed commit-type mapping — see scripts/changelogBody/changelogBody.mts
  • Kept commit types: feat, fix, perf (everything else, e.g. chore/refactor/test/ci, is dropped before the AI step ever sees it)
  • Under the Hood entries are consolidated into one bullet with all their PR links, no package sub-header
  • Package sections: #### <package-name>, alphabetical within a type
  • Bullet entries: - <message> ([PR #N](url)); PR url format https://github.com/forcedotcom/salesforcedx-vscode/pull/<num>
  • Multiple PRs for one entry: comma-separate ([PR #A](...), [PR #B](...), [ISSUE #C](...), [DISCUSSION #D](...))
  • Include [ISSUE #N](https://github.com/forcedotcom/salesforcedx-vscode/issues/N) or [DISCUSSION #N](https://github.com/forcedotcom/salesforcedx-vscode/discussions/N) when listed in the PR's "What issues does this PR fix or reference?" section

Package filtering (auto)

  • If salesforcedx-vscode-core is touched, all other touched packages (except docs) are dropped for that commit
  • If salesforcedx-vscode-services is touched alongside exactly one other (non-docs) package, salesforcedx-vscode-services is dropped and the other package keeps the entry
  • Only packages starting with salesforce or docs count; path segments named images or test are ignored when detecting touched packages
  • A commit whose surviving paths touch no qualifying package has an empty package set and goes to Under the Hood

Commit parsing (auto)

  • Requires conventional type(scope): message + trailing (#PR) to appear in the commit subject
  • Strips [W-XXXXXXXX] GUS refs from the subject before it reaches the AI step
  • No dedupe against the existing changelog file — the range is disjoint by construction (see Commit details above)

Dedupe / merge rules (post-generation)

  • Same PR listed under multiple packages: keep under the most user-relevant package, delete others (see Rule 3 above)
  • Same PR listed twice in a section: collapse to one bullet
  • Empty #### <package> subsections: leave in place if auto-generated (keeps structure obvious), or remove during polish — match surrounding style
  • Patch release rolling into next: if v66.Y.A shipped but entries were missing, merge into v66.Y.B section and update the header date; see chore: merge ... changelogs

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.