A long time coming

Since the release of v11 in March of last year, there have been a lot of questions and feedback around the timeline for both v10 and v11. As the ecosystem around the Carbon Design System continues to mature and grow, we’d like to begin setting expectations for the timeframe around each major release we publish.

Over the past few months we have engaged with many teams within IBM on this topic. We consulted with both early v11 adopters and those still using v10 to help determine a realistic and reasonable time window for support of major versions. It was clear from very early on that due to the scale of IBMs teams and operations there is a strong need for our versions to have a plan of long term support.

The plan

We’ve landed on a release schedule we believe reflects the realities of enterprise product development while also balancing the finite resources of teams working to grow and maintain the Carbon Design System ecosystem.

Release phases

In this plan, each major release has three phases; Prerelease, Active and Maintenance.

Prerelease

The prerelease phase is intended to be the opportunity for early adopters, library authors, and other strategic ecosystem partners to begin to evaluate and integrate new changes into their codebases. For v11, this phase was eight months long and spanned four prerelease/beta releases. We hope to extend this timeframe even further for our next major.

Active

A release in the Active phase receives biweekly minor releases containing new features and fixes. The work we deliver into main every day is considered unstable. Every two weeks we package up these changes into a new minor version that is published from main to the current Active major. Consuming projects should always aim to follow the Active release.

Maintenance

For a release in the Maintenance phase, patch releases are published containing security patches and critical bug fixes. When a version moves from Active to Maintenance, consuming projects should begin migrating to the new Active major version.

During Maintenance we also consider adding non-critical bug fixes on an ad hoc basis, by request only. This model has been working well for v10 so far and a number of fixes have already been back-ported from v11 to v10. If you’re using v10 and there is a v11 fix you’d like to see in v10, please open an issue.

Major timelines

v9 and v10

The release of v11 ushered in two changes — v9 no longer being supported, and the transition of v10 to the Maintenance phase. As shown in the plan, the v10 release will continue to be supported by our team through September of 2024.

This timeframe intentionally aligns with the fall planning period many teams have, and provides over 16 months to plan and accomplish a migration to v11. To help support this timeframe we are also actively working to reduce the time it takes to migrate to v11.

v11

For the current major version, v11, it is in active development. All new features and fixes go here and are released biweekly in new minor versions. We anticipate moving v11 to Maintenance when v12 is released.

The future and beyond

Our next major version v12 is not quite in view yet, the timeline outlined in the chart is just an ideal proposal.

We’re currently ideating on ways that we could accelerate this release schedule without impacting teams. The next major version will be an opportunity to explore different approaches to change management and breaking changes to improve overall stability of our packages. There will be more on this to come, but ultimately we want our next major to be even more seamless from a migration standpoint.

What does this plan cover?

For now this plan covers the design and development assets under maintenance of the Carbon Design System core team. This includes the @carbon/react and @carbon/styles packages, as well as all other packages within the carbon monorepo. Soon we will provide more scoped information for @carbon/charts and @carbon/web-components. This plan also includes all design guidance and design kit assets (Figma, etc.) present on carbondesignsystem.com

The broader open-source Carbon Design System ecosystem is a complex array of assets spanning across multiple teams and library maintainers both inside and outside of IBM. This release plan may not map 1:1 for all these instances. We’ll work with library and framework variant authors to help establish how their release plans can ladder up into this plan. Ultimately we want the entire ecosystem to be in lockstep with one another and avoid fragmentation where possible. If you’d like to discuss plans for an asset or library you maintain, please reach out!

A living document, subject to change

We know this plan is the result of feedback from only a snapshot in time and we anticipate that the needs for version support will change over time. Ultimately, the dates and phases outlined in the release schedule are subject to change.

The plan will live in the carbon GitHub repository and future changes will be made there. If you have thoughts or concerns on any of this, we’d love to get your feedback and start a dialog in the GitHub discussion for this topic. This crucial feedback from the Carbon community will help guide future changes to this plan. Thank you again to the many teams that already helped to inform this work so far!

Taylor Jones is a Software Engineer based out of Austin, TX working on the Carbon Design System. The above article is personal and does not necessarily represent IBM’s positions, strategies, or opinions.

Questions or comments about Carbon? Reach out at carbon@us.ibm.com or tweet us @_carbondesign.

Announcing the Carbon Design System Release Schedule was originally published in _carbondesign on Medium, where people are continuing the conversation by highlighting and responding to this story.

Expanding on our April announcement that Carbon will be moving to Dart Sass from Node Sass, we wanted to take a closer look at how projects using carbon-components can prepare for this change today, before v11 is released.

Transition from node-sass to sass

For those unfamiliar with recent changes in the sass ecosystem, node-sass is a very popular wrapper around the LibSass implementation of sass that has been deprecated. sass is now the recommended package and is built atop the dart-sass implementation.

Beginning in v11, Carbon will require the use of sass. To migrate, it typically will require just one step — swap the node-sass dependency for sass. In most projects it’s included as a devDependency.

yarn remove node-sass
yarn add sass --dev

// or with npm:

npm uninstall node-sass
npm install sass --save-dev

The Sass team has outlined further migration information including a list of known compatibility issues and the potential fixes available.

Handling multiple instances of node-sass

If your project is a collection of multiple packages, perhaps organized as a monorepo, you’ll want to replace all usages of node-sass with sass. It may be helpful to search your dependency tree for node-sass to gather a list of sub dependencies or packages you may need to update or reconfigure.

yarn why node-sass

// or with npm:

npm ls node-sass

The sass package exports the same API as node-sass and is intended to be an in-place update without any required changes. If you’re using webpack, sass-loader should default to using the sass implementation if you remove the implementation key from your options config. In some cases you may still need to explicitly require the correct implementation.

{
  implementation: require('sass')
}

Confirm your project is using the correct implementation

One way to confirm that your project is probably using the correct implementation is to run a small smoke test using import-only files. With this approach you can add a couple test files, tmp.import.scss and tmp.scss. If you import this in your central entrypoint file, node-sass will use tmp.scss while sass will use tmp.import.scss.

// index.scss
@import './tmp';

// _tmp.scss
@debug '_tmp.scss was processed, likely using node-sass';

// _tmp.import.scss
@debug '_tmp.import.scss was processed, likely via sass';

After running a build, you should see output on your console indicating which file was processed.

Resolve common problems with the Sass Migrator

Depending on the sass language features your project is using, you may encounter deprecation warnings or other messages after swapping out node-sass for sass. These are only warnings and should not impact the success of your build.

One very common deprecation warning that was present in the Carbon codebase itself was the deprecation of using a slash / for division. Thankfully, the Sass team provides a sass-migrator CLI to assist with upgrading a codebase to new language features. We appreciated being able to run the division migration to update our files automatically with the new math.div function intended to replace slash for division.

sass-migrator division path/to/styles/*.scss

For full details, check out the documentation for sass-migrator.

Include node_modules as a load path

In v11, you will need to configure Sass to be able to find packages from your node_modules folder. To do this, use the includePaths option and set its value to an array of load paths where Sass should look to find node_modules folders.

For most projects, this configuration will look like this:

{ 
  "includePaths": ["node_modules"] 
}

If you are using the Sass CLI directly, use the --load-path flag:

$ sass --load-path=node_modules style.scss style.css

In some projects, particularly those organized as a monorepo, the build path may not be colocated with node_modules. In this case, it may be helpful to use a javascript-based config file so that multiple node_modules paths can be resolved dynamically.

const path = require('path');

module.exports = {
 includePaths: [
  path.resolve(__dirname, '../../node_modules'),
  path.resolve(__dirname, '../../../../node_modules'),
 ],
};

Note that this config is an array value, and earlier load paths will take precedence over later ones. Read more about Sass load paths in the documentation.

A note on Sass Modules

The most prominent feature available through the sass dependency is the new Sass module system. Beginning in v11, Carbon will provide a new @carbon/styles package built using Sass Modules. This does not mean that your codebase needs to migrate right now to use Sass Modules. The Carbon styles will continue to work using @import for now with some tweaks if your styles are using Carbon tokens, functions, or mixins. We’ll provide more in-depth information on this as we near the v11 release through new migration documentation.

There are numerous benefits to using Sass Modules including smaller bundle size and increased build performance. If you’re interested to learn more and would like to get a jump start on it, there is a module migration available through the sass-migrator.

Continuing the path towards v11

These steps should begin to prep your project for the changes coming in the next major version of Carbon.

Overall these changes should be pretty uneventful, but if you encounter issues moving off of node-sass please contribute feedback in our Github discussion. So far we’ve seen that most issues are likely be related to config options and may not be easily reproducible outside of your project environment. It’s always helpful to narrow down your issue into a reproducible codesandbox example when reporting problems.

As portions of our v11 work stream are completed we’ll be publishing more migration documentation and posts like these to communicate what’s coming. Be on the lookout for our next beta release soon!

Taylor Jones is a Software Engineer based out of Austin, TX working on the Carbon Design System. The above article is personal and does not necessarily represent IBM’s positions, strategies, or opinions.

Questions or comments about Carbon? Reach out at carbon@us.ibm.com or tweet us @_carbondesign.

One quick way to get ready for Carbon v11 was originally published in _carbondesign on Medium, where people are continuing the conversation by highlighting and responding to this story.