Create a MWC Update Guide

[ryan-henness-trimble]

Prerequisites

• [X] I have searched for duplicate or closed feature requests
• [X] I have read the contributing guidelines

Proposal

Now that the library is mature enough to start introducing breaking changes, we should discuss how we want to help consumers update their usages when breaking changes occur

I see 3 options:

1. A markdown file called UPDATE_GUIDE.md at the repository root
2. A page in the Storybook site
3. An interactive site that let's the user pick which version they are starting with and which version they are updating to. That would then generate all the necessary steps they would take to update. This is a larger effort, and possibly overkill for the speed of development of this project

Either way, I think these options would all contain the same information: a descriptive list of what has been removed/deprecated and how to resolve issues that arise while updating from one version to the next

Motivation and context

No response

Which npm package?

@trimble-oss/modus-web-components

Priority

Low

What is the product name the feature is requested for?

Modus Web Components

What is the team name the product belongs to?

Trimble

What is the division name the team belongs to?

Modus

[ryan-henness-trimble]

Added the 'deprecation' label to support this effort

[coliff]

I'd vote for "2 - a page on the Storybook site". That way the link can be shared easily between colleagues.

Definitely not a fan of the idea of "3 - maintaining different versions", we want to encourage everyone to be on the latest version as much as possible.

[msankaran0712]

I would also vote for 2 - a page on the Storybook site. Have seen a similar thing in other design systems https://react-bootstrap.github.io/migrating/#summary-of-breaking-changes-from-v1x, https://mui.com/material-ui/migration/v5-component-changes/, https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md#version-7x-accordion-group

[ryan-henness-trimble]

I'd vote for "2 - a page on the Storybook site". That way the link can be shared easily between colleagues.

Definitely not a fan of the idea of "3 - maintaining different versions", we want to encourage everyone to be on the latest version as much as possible.

I think I like 2 best, too

Just for future reference, this is the type of thing I was thinking for 3 - it could be more useful for teams who have fell behind quite a lot in versions https://update.angular.io/

[ryan-henness-trimble]

Here's the draft PR: https://github.com/trimble-oss/modus-web-components/pull/1355

[leohaughton]

I found my way here from #1283

When upgrading Modus Web Components I found a breaking change. Given that we only incremented a patch semver version I would have expected this to be backwards compatible.

Could we use JSDoc comments to tell the user that the specific field is deprecated?

[coliff]

Given that we only incremented a patch semver version I would have expected this to be backwards compatible.

As Modus Web Components is currently on v0.x there are still breaking changes from time to time which we make sure to call out in the Release Notes.

Once we release v1.0.0 there won't be any breaking changes without a major version number bump as we'll try and strictly follow SemVer.

It's a good point you raise though still, we perhaps should have at least bumped from v0.1 to v0.2 when introducing breaking changes are introduced.

[msankaran0712]

@coliff @leohaughton @ryan-henness-trimble Maybe we can consider adding more details to the release notes. @ryan-henness-trimble are we still doing this?

[ryan-henness-trimble]

@msankaran0712 That seems like a good idea, I think the main goal here is to have somewhere we can point consumers to when breaking changes have been introduced. It may be nice to add a section to the release notes that goes into more detail about what is breaking and how to resolve them