docs(swc): rework CHANGELOG for 2.0.0-beta1 initial release by rubencarvalho · Pull Request #6266 · adobe/spectrum-web-components

rubencarvalho · 2026-05-11T14:00:20Z

Description

Reworks 2nd-gen/packages/swc/CHANGELOG.md ahead of the 2.0.0-beta1 release.

Replaces the 0.0.2 / 0.0.3 / 0.0.4 pre-release history with a single 2.0.0-beta1 section.
Adds one Minor Changes entry per component shipping in the initial public release of @adobe/spectrum-wc, modelled on the Button entry's level of detail (renames, removals, additions, a11y improvements, fixed SWC issue numbers, link to the consumer migration guide).
Components covered: button, avatar, badge, divider, illustrated-message, progress-circle, status-light, tabs, typography.
Adds an entry for the new Conversational AI pattern (no 1st-gen counterpart), summarizing the 11 elements it ships.

Motivation and context

@adobe/spectrum-wc is going from 0.0.4 to 2.0.0-beta1. The CHANGELOG should reflect the actual scope of the initial public release rather than the internal pre-release patch history that accumulated during dev. Documenting every component up front gives consumers a single place to see what's shipping and how each component differs from its 1st-gen counterpart.

Related issue(s)

N/A (release prep)

Screenshots (if appropriate)

N/A — Markdown file.

Author's checklist

I have read the CONTRIBUTING and PULL_REQUESTS documents.
I have reviewed at the Accessibility Practices for this feature, see: Aria Practices
I have added automated tests to cover my changes.
I have included a well-written changeset if my change needs to be published.
I have included updated documentation if my change required it.

Tests and changeset intentionally skipped: documentation-only edit to the package CHANGELOG; this is the release note that will accompany the 2.0.0-beta1 cut, so a separate changeset would be redundant.

Reviewer's checklist

Includes a Github Issue with appropriate flag or Jira ticket number without a link
Includes thoughtfully written changeset if changes suggested include patch, minor, or major features
Automated tests cover all use cases and follow best practices for writing
Validated on all supported browsers
All VRTs are approved before the author can update Golden Hash

Manual review test cases

CHANGELOG renders correctly
1. Open 2nd-gen/packages/swc/CHANGELOG.md on this branch in a Markdown previewer (or on GitHub).
2. Confirm the 2.0.0-beta1 heading is the only version section.
3. Confirm all entries appear as top-level bullets under Minor Changes.
Consumer migration guide links resolve
1. For each component entry with a "consumer migration guide" link, click through on the deployed Storybook for this branch.
2. Expect the link to land on the corresponding migration guide MDX page. Flag any 404s — the URL pattern I used mirrors the Button example (/?path=/docs/components-<name>-consumer-migration-guide--readme) and may need adjustment to match the actual story IDs Storybook generates.
Content accuracy spot-check
1. For each component, cross-reference the bullet list in the CHANGELOG against its consumer-migration-guide.mdx (or migration.md).
2. Flag any inaccuracies, missing breaking changes, or fixed SWC-XXX issue numbers I should add.

Device review

Did it pass in Desktop?
Did it pass in (emulated) Mobile?
Did it pass in (emulated) iPad?

Accessibility testing checklist

Keyboard (required — document steps below)
1. Open the CHANGELOG on GitHub or in a Markdown preview.
2. Tab through the page.
3. Expect focus to only land on the anchor links inside the entries (consumer-migration-guide URLs and pattern-README URL); no traps.
Screen reader (required — document steps below)
1. Navigate the file by heading with a screen reader.
2. Expect: H1 (@adobe/spectrum-wc), H2 (2.0.0-beta1), H3 (Minor Changes, Patch Changes); bullet items announce in order with no skipped heading levels.

changeset-bot · 2026-05-11T14:00:28Z

⚠️ No Changeset found

Latest commit: 1d68cc7

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

github-actions · 2026-05-11T14:11:45Z

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

When a visual regression test fails (or has previously failed while working on this branch), its results can be found in the following URLs:

Deployed to Azure Blob Storage: pr-6266

If the changes are expected, update the current_golden_images_cache hash in the circleci config to accept the new images. Instructions are included in that file.
If the changes are unexpected, you can investigate the cause of the differences and update the code accordingly.

Replace the 0.0.x pre-release history in @adobe/spectrum-wc's CHANGELOG with a single 2.0.0-beta1 section listing one entry per component shipping in the initial public release (button, avatar, badge, divider, illustrated-message, progress-circle, status-light, tabs, typography) plus the new Conversational AI pattern. Each entry is a one-liner with links to the component docs and the consumer migration guide.

Establish a unified changelog format for @adobe/spectrum-wc where changeset bodies flow verbatim into the CHANGELOG — no commit hashes, no author attributions, no reformatting. - Add scripts/changelog-passthrough.cjs: hybrid changelog function that passes through entries for 2nd-gen and delegates to @changesets/changelog-github for 1st-gen - Update .changeset/config.json to use the passthrough script - Add contributor guide (15_changelog-strategy.md) with format spec - Add strategy proposal doc for team review - Cross-link from PR guide and release guide Co-authored-by: Cursor <cursoragent@cursor.com>

Co-authored-by: Cursor <cursoragent@cursor.com>

…om 2nd-gen CHANGELOGs The changesets library hardcodes "### Minor Changes" / "### Patch Changes" headings. A new clean-changelog.cjs script removes them so 2nd-gen CHANGELOGs have flat bullets under the version heading. Wired into publish.js to run automatically after `yarn changeset version`. Co-authored-by: Cursor <cursoragent@cursor.com>

cdransf · 2026-05-12T21:09:26Z

+];
+
+function is2ndGen(changeset) {
+  return changeset.releases.some((r) => SECOND_GEN_PACKAGES.includes(r.name));


~~Is it possible to have a changeset that includes a 1st gen package with a name contained in SECOND_GEN_PACKAGES, resulting in unexpected true cases? ✨~~

I think the danger here is if a changeset includes a 1st and 2nd gen package then the func will return true and the 1st gen entry gets the passthrough format instead of the @changesets/changelog-github format. ✨🤔

cdransf · 2026-05-12T21:10:21Z

+ * Hybrid changesets changelog function.
+ *
+ * - 2nd-gen packages (`@adobe/spectrum-wc`, `@spectrum-web-components/core`):
+ *   Returns changeset bodies verbatim as CHANGELOG bullets. No commit


I'm being pedantic here but it's not verbatim, as we're prepending - 😇✨

Suggested change

* Returns changeset bodies verbatim as CHANGELOG bullets. No commit

* Returns changeset bodies as CHANGELOG bullets. No commit

cdransf · 2026-05-12T21:14:35Z

+      return '';
+    }
+
+    return '\n\n' + lines.map((line) => `- ${line}`).join('\n');


Does this break markdown headings by prepending - to them? ✨

- Use `every` instead of `some` in `is2ndGen` so mixed changesets (1st + 2nd gen) fall back to the GitHub changelog format safely - Fix JSDoc: "verbatim" -> "as CHANGELOG bullets" (we prepend `- `) - Skip `- ` prefix for lines starting with `#` to avoid breaking markdown headings in changeset bodies Co-authored-by: Cursor <cursoragent@cursor.com>

rubencarvalho requested a review from a team as a code owner May 11, 2026 14:00

rubencarvalho marked this pull request as draft May 11, 2026 17:06

rubencarvalho added Status:Ready for review PR ready for review or re-review. 2nd gen These issues or PRs map to our 2nd generation work to modernizing infrastructure. labels May 11, 2026

rubencarvalho marked this pull request as ready for review May 11, 2026 17:21

rubencarvalho force-pushed the rcarvalho/docs-changelog-2-0-0-beta1 branch from 8d15b0e to d1d85d5 Compare May 11, 2026 17:24

Rajdeepc self-assigned this May 12, 2026

Rajdeep Chandra and others added 3 commits May 12, 2026 17:41

docs(swc): reformat CHANGELOG.md to match 2nd-gen changelog strategy

08accbc

Co-authored-by: Cursor <cursoragent@cursor.com>

cdransf reviewed May 12, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(swc): rework CHANGELOG for 2.0.0-beta1 initial release#6266

docs(swc): rework CHANGELOG for 2.0.0-beta1 initial release#6266
rubencarvalho wants to merge 5 commits into
mainfrom
rcarvalho/docs-changelog-2-0-0-beta1

rubencarvalho commented May 11, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented May 11, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 11, 2026 •

edited

Loading

Uh oh!

cdransf May 12, 2026 •

edited

Loading

Uh oh!

cdransf May 12, 2026

Uh oh!

cdransf May 12, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	* Returns changeset bodies verbatim as CHANGELOG bullets. No commit
	* Returns changeset bodies as CHANGELOG bullets. No commit

Conversation

rubencarvalho commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation and context

Related issue(s)

Screenshots (if appropriate)

Author's checklist

Reviewer's checklist

Manual review test cases

Device review

Accessibility testing checklist

Uh oh!

changeset-bot Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

github-actions Bot commented May 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Branch Preview Links

🔍 First Generation Visual Regression Test Results

Uh oh!

cdransf May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cdransf May 12, 2026

Choose a reason for hiding this comment

Uh oh!

cdransf May 12, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rubencarvalho commented May 11, 2026 •

edited

Loading

changeset-bot Bot commented May 11, 2026 •

edited

Loading

github-actions Bot commented May 11, 2026 •

edited

Loading

cdransf May 12, 2026 •

edited

Loading