Naming, scoping, and categorizing migrations

[sam-b-rose]

👋 TL;DR See the proposed new naming and structure at the below 👇

Proposed new naming and structure

This is my proposed naming and directory structure for our current migrations based on my research. Would love to hear your thoughts!

migrations/
├─ common/
│  ├─ component-replace-prop
├─ v9/
│  ├─ sass-replace-border
│  ├─ sass-replace-breakpoints
│  ├─ sass-replace-color
│  ├─ sass-replace-spacing
│  ├─ sass-replace-z-index
│  ├─ sass-replace-text-emphasis
│  ├─ styles-tokenize-font
│  ├─ styles-tokenize-motion
│  ├─ styles-tokenize-shape
│  ├─ styles-tokenize-space
├─ v10/
│  ├─ text-replace-components
│  ├─ card-to-v10

Overview

The migrations in polaris-migrations is growing but we don't currently have a standardized naming convention or categorization strategy for them. The scope of each migration can also vary–replacing a single Sass function to replacing all declaration values for a subset of properties.

How should we structure migrations to accomplish the following:

• The scope and intent of a migration is always obvious to users.
• Migrations are in a playable in sequence (ex: v8 -> v9 -> v10).
• Allow us to go back and patch older migrations if necessary.

Other codemod references:

CodeshiftCommunity
Material UI
Next.js Codemods
Storybook

Scope

We should revisit the scope of some of our current migrations, narrowing down what they target.

For example, we can split current the current replace-sass-border migration into two migrations: replace-sass-border and tokenize-styles-border for example.

One handles replacing the legacy-polaris-v8.border() function while the other focuses on tokenizing static declaration values border-radius: 2px; to border-radius: var(--p-border-radius-05);.

We can then create composed migrations (preset-sass-v10 or something similar) to apply several migrations at once. The presets are designed to migrate from one version to another (v8 to v9) and should only need to be run once.

Naming convention

The naming of a migration should be clear so that is is apparent to the user what target is being modified and the action it is performing.

Proposed

// format
[type]-[action]-[target]

// examples
sass-replace-spacing
sass-replace-border
styles-tokenize-space
styles-tokenize-fonts
text-replace-components
component-replace-prop

// presets
sass-preset-v9
styles-preset-v9
react-preset-v9

Alternative

// format
[action]-[type]-[target]

// examples
replace-sass-spacing
replace-sass-border
tokenize-styles-space
tokenize-styles-fonts
replace-text-components
replace-component-prop

// presets
preset-sass-v9
preset-styles-v9
preset-react-v9

With version

// format
[version]/[action]-[type]-[target]

// or
[version]-[action]-[type]-[target]

// examples
v9/replace-sass-spacing
v9-replace-sass-border
v9-replace-text-components
v9-replace-component-prop

// presets
v9-preset-sass
v9-preset-styles
v9-preset-react-v9

Versioning

We limit the scope of a migration to a specific version–from one API to another. This can be organized with the directory structure and also documented on the README.md and/or website.

migrations/
├─ common/
│  ├─ component-rename-prop
├─ v9/
│  ├─ sass-replace-border
│  ├─ sass-replace-spacing
│  ├─ styles-tokenize-space
├─ v10/
│  ├─ text-replace-components
│  ├─ card-replace-props

[alex-page]

Love this. I don't have any strong suggestions but this seems logical and scalable to me.

[chloerice]

Love this direction, Sam 🙌🏽

My vote is for the [type]-[action]-[target] format, because it lends itself to logical doc organization by technology. For example, folks not using Sass could skip over that section of documentation and dig into the Styles section.

I also like the idea of separating out the function migrations so they're easier for folks to review after running in their apps. We can still group them together in the docs, something like:

# Migrations
// Introduction to migrations yada yada yada...

## Sass 
// Legacy Sass API migrations yada yada yada...

### Border functions and mixins

**`border()` function**
...

**`border-radius()` function**
...

**`border-width()` function** 
...

**`focus-ring`** mixin
...

[lgriffee]

Huge +1 to what Chloe said!

Love this direction Sam!! 🤩🎉❤️🚀✨ The [type]-[action]-[target] format also makes the most sense to me. And splitting out the function migrations from the strictly style migrations will make it much clearer what each script is doing!

[aaronccasanova]

Also +1ing Chloe's feedback! I think the proposed [type]-[action]-[target] pattern reads well and will make migrations easy to navigate as we continue adding more.

Regarding "With versions", I think I prefer [version]-[type]-[action]-[target] as opposed to mapping names to the migrations directory structure. That said, if [version]/[type]-[action]-[target] reduces complexity in the module resolution I think that's a good argument for the / separator.

Awesome research and breakdown @samrose3!!

[sam-b-rose]

Just following up here with the decided approach. #7606 updates the current migration naming and scope into the following:

react-[action]-[target]
scss-[action]-[target]
styles-[action]-[target]