Changelog

Changelog Polish

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

Scope: the all-extensions release changelog at packages/salesforcedx-vscode/CHANGELOG.md. Root CHANGELOG.md contains full historical changelog (automatically prepended by scripts/prepend-release-changelog.js, run as part of the same promote job) — do not edit manually. Per-package CHANGELOG.md files (e.g. packages/salesforcedx-vscode-i18n/CHANGELOG.md) are scoped to their own package and out of scope here.

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's next scheduled run (Wednesdays, 7 AM UTC). That job reads develop's current packages/salesforcedx-vscode/CHANGELOG.md, relabels the header to the stable version, and bakes it into the stable VSIX. Once that's run, the content is frozen inside the built artifact — fixing it afterward means manually re-injecting into the release's VSIX asset, not editing this file.

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.