Polaris migrations platform

[sam-b-rose]

🛠️ Tooling to automate breaking changes and increase mainline adoption

Problem

Mainline coverage for custom components in Shopify/web is at 29% and is negatively affected by deprecated Sass functions that we added to unblock shipping v9. Shopify and third-party developers need tooling to apply feature and deprecation migrations between major versions.

Manual token and component updates are tedious and prone to error–documentation tables are not a sufficient solution. Building a new migration platform would assist with large-scale, automated codebase refactors to ensure migration accuracy. This would remove tedious manual work and improve our overall speed and thoroughness when making system-wide updates or breaking changes. Providing this tooling would increase coverage and adherence to mainline.

Outcomes

• 5% increase to mainline coverage
• 30% (15 to 40%) increase coverage of custom component tokens
• Start removing some of the legacy-polaris-v8-public-api.scss from Shopify/web
• Create a new migration tool that will allow us to author and apply migrations (npm package @shopify/polaris-migrator or @shopify/polaris-codemod)
  Establish migration documentation on polaris.shopify.com (Next.js docs example)
• Future migrations can build upon the patterns created
• Potentially unblock the usage of @shopify/polaris-stylelint in Shopify/web

Create the platform

• Create prototype @shopify/polaris-migrator package #6943
• Test prototype in Shopify/web on spacing Sass function migration
• Test prototype in Shopify/web on Text component migration
• Create @shopify/plugin-polaris package #7166
• Add migrator docs to polaris.shopify.com #7030

Migrations

• Add migration for sass padding and margin length values #7264
• Add gap properties to replace-spacing-lengths migration #7342
• Add migration for sass z-index fn #7310
• Add migration for sass padding and margin length values #7264
• Add migration to replace-static-mixins-with-declarations #7216
• Migrate static breakpoint mixins #7153
• Create Sass color() function migration #7375
• Add migration to replace-typography-declarations #7335
• Add migration to replace-border-declarations #7387
• [Migrator] Add migrate-sass-transition migration for transition durations & easing #7403
• Replace focus-ring mixin with simplification #7475
• Unblock usage of stylelint --fix #7476
• Align communication and documentation of migrations #7477
• [Typography foundations] Replace usage of deprecated type components #6588]

[BPScott]

Is this for the web codebase only or is the idea to scale to other consumers of polaris too?

If it is just for web - or even if it is starting in web - , I wonder if placing this tooling in the web repo's tooling folder, would shorten testing and feedback loops - removing the need to perform snapit releases for testing. Once the code is proven in the web, general-purpose aspects could be pulled out into the polaris monorepo.

[sam-b-rose]

Is this for the web codebase only or is the idea to scale to other consumers of polaris too?

This will intended for all Polaris consumers! I do like the idea of possibly creating a prototype in web. Are there any smaller repos that would be another good testing ground?

[alex-page]

@samrose3 the platform is built, going to make issues for the docs on polaris.shopify.com