Introduction #

The deprecation process for Spectrum Web Components (SWC) outlines the process for identifying, communicating, and removing deprecated components from the library. This document provides process for managing deprecation and ensuring a smooth transition for consumers.

Things change and evolve in libraries like SWC, but we don't want consumers to be surprised by those changes. We think that by providing clearer expectations to when we intent to remove potentially useful APIs, consuming teams have the opportunity to talk with us to better understand their needs before we finalize changes. If a deprecation is unexpected to you please reach out to the SWC team.

Deprecation timeline #

By default the removal of functionality or a component is considered for the next major release after the major release for which it was marked as deprecated. For example, a function marked as deprecated during a SWC 1.x will be removed at the next major release, e.g. SWC 2.0.

Deprecation policy #

Warning levels #

Deprecation warnings are categorised into the following levels:

Communication #

Deprecation notices will be added to the affected components, including a warning message and a link to documentation for migration guidance. Notices will be prominently displayed in the documentation and release notes.

Deprecation process #

  1. Identification: Components or features that are no longer recommended for use will be identified through internal review or community feedback.
  2. Announcement: Deprecation of a component will be announced in the release notes and on the SWC website. The announcement will include the deprecation level and migration guidance.
  3. Warning Implementation: A deprecation warning will be added to the affected components, using the window.__swc.warn method to display the warning message.
  4. Package.json Update: The package.json file of the deprecated component will be updated with a deprecationNotice key containing the deprecation message and guidance.
  5. Documentation Update: Documentation for the deprecated component will be updated to include the deprecation notice and migration guidance.
  6. Migration Period: Deprecated components will remain functional for a specified period to allow users to migrate to alternative solutions.
  7. Removal: Deprecated components will be removed from the library in the 1.0.0 release. Prior to removal, the deprecation level will be changed to red to indicate the urgency of migration.

Examples #

Deprecating a function, method or class #

Its important functions, methods and classes are never immediately removed from code. Instead they are deprecated for at least 1 major release before being removed.

A function,method or a class can be depreacted with a depreacted tag in the JSdoc to properly surface up to its context and API

* @deprecated since 0.42.1

const enableScrollIntoView = () => {

Adding Deprecation Notice #



    `<${this.localName}> is deprecated. Use a Button Group to show any additional actions related to the most critical action.`,
    { level: 'deprecation' }

Adding package.json update #



    "name": "@spectrum-web-components/split-button",
    "version": "0.0.1",
    "deprecationNotice": "@spectrum-web-components/split-button is deprecated."

Backward compatibility #

Breaking changes in Spectrum Web Components will only happen in the platform releases (ie: major version releases). Any planned breaking changes will be communicated with advance notice through the deprecation method and documentation.

Deprecations will be removed at the next major release, if possible. If the specifics for a deprecation can't be constrained to the next major release, we'll minimally mark things as deprecated for 2 releases or six months (whatever is smaller).