Breaking change flow

[rosslo]

Why: As we are doing design sync stuff, we will have to change the style or behavior which might cause a breaking change.

How: For any potential breaking change, before we merge the change into v4, we should

• Ensure the change being backward compatible.
• Use console.warning to warn the developer about the legacy props.
• Mark deprecated codes with @deprecated tag so the other developers can easily be aware of it from IDE.
• Add the announcement about the legacy stuff on the storybook and slack (after merging into v4).
• Create an issue for removing legacy features.

So the breaking changes won't break the production or block the other features and we won't be forced to migrate it on the projects asap.

After we migrate the breaking change on projects and merge the branch into staging, we can start to remove the legacy codes on glints-aries.

Example: The two examples below both blocked the other features release before because we didn't make the change be backward compatible.

• Color:

  • Slack: https://glints.slack.com/archives/CS09D0LJX/p1612494365026900
  • PR: https://github.com/glints-dev/glints-aries/pull/583
  • Breaking change: Some color variables got renamed or removed.
  • How should we do:
    1. Add new colors and still keep the deprecated colors in src/Utils/Colors.ts.
    2. Remove deprecated colors from the storybook.
    3. Merge branch into v4 and announce the coming breaking changes on slack.
    4. Upgrade glints-aries and replace the legacy color variables with new ones on projects.
    5. After we merge the breaking change migration into staging, we can remove the legacy colors on glints-aries.

• TextField:

  • Slack: https://glints.slack.com/archives/CS09D0LJX/p1610432559027600?thread_ts=1607424021.047700&cid=CS09D0LJX
  • PR: https://github.com/glints-dev/glints-aries/pull/553
  • Breaking change: The style of TextField got totally redesigned.
  • How should we do:
    1. Add a new component called TextInput according to the design guideline.
    2. Add description on TextField storybook about this component that has been deprecated from the design system and what is the alternative.
    3. Announce the change on slack after the merge.
  • Why don't we remove TextField: Because TextField is still used at many places and probably has feature or bug request in the future. Therefore, we should still maintain the TextField in glints-aries.

[rosslo]

Question:

• Should we build a tool/ script to find the use of an Aries component with a given property?

Concern:

• Aries component wrapped by styled is not trackable by jscodeshift.

[westwood846]

• Should we build a tool/ script to find the use of an Aries component with a given property? I think I could adapt my tool for counting the usages of the code units for this quite easily.

[westwood846]

I think @deprecated is the way to go. We just have to make it sufficiently visible that a code unit it going to be removed. That way we prevent new usages. And then we can replace the old usages.