65 lines
2.9 KiB
Markdown
65 lines
2.9 KiB
Markdown
|
# Contributing
|
||
|
|
|
||
|
|
## Understanding the codemod
|
||
|
|
|
||
|
|
The codemod is a tool that helps developers migrate their codebase when we introduce changes in a new version. The changes could be deprecations, enhancements, or breaking changes.
|
||
|
|
|
||
|
|
The codemods for JavaScript files are based on [jscodeshift](https://github.com/facebook/jscodeshift) which is a wrapper of [recast](https://github.com/benjamn/recast).
|
||
|
|
|
||
|
|
The codemods for CSS files are based on [postcss](https://github.com/postcss/postcss).
|
||
|
|
|
||
|
|
## Adding a new codemod
|
||
|
|
|
||
|
|
1. Create a new folder in `packages/mui-codemod/src/*/*` with the name of the codemod.
|
||
|
|
2. The folder should include:
|
||
|
|
- `<codemod>.js` - the transform implementation
|
||
|
|
- `index.js` - exports the transform function
|
||
|
|
- `postcss-plugin.js` - the postcss plugin (optional)
|
||
|
|
- `postcss.config.js` - the postcss config file (optional)
|
||
|
|
- `<codemod>.test.js` - tests for the codemods (use jscodeshift from the `testUtils` folder)
|
||
|
|
- `test-cases` - folder with fixtures for the codemod
|
||
|
|
- `actual.js` - the input for the codemod
|
||
|
|
- `expected.js` - the expected output of the codemod
|
||
|
|
- `actual.css` - the input for the postcss plugin (optional)
|
||
|
|
- `expected.css` - the expected output of the postcss plugin (optional)
|
||
|
|
3. Use [astexplorer](https://astexplorer.net/) to check the AST types and properties
|
||
|
|
- For JavaScript codemods set </> to @babel/parser because we use [`tsx`](https://github.com/benjamn/recast/blob/master/parsers/babel.ts) as a default parser.
|
||
|
|
- For CSS codemods set </> to postcss
|
||
|
|
4. [Test the codemod locally](#local)
|
||
|
|
5. Add the codemod to README.md
|
||
|
|
|
||
|
|
## Testing
|
||
|
|
|
||
|
|
I recommend to follow these steps to test the codemod:
|
||
|
|
|
||
|
|
- Create an `actual.js` file with the code you want to transform.
|
||
|
|
- Run [local](#local) transformation to check if the codemod is correct.
|
||
|
|
- Copy the transformed code to `expected.js`.
|
||
|
|
- Run `pnpm tc <codemod>` to final check if the codemod is correct.
|
||
|
|
|
||
|
|
💡 The reason that I don't recommend creating the `expected.js` and run the test with `pnpm` script is because the transformation is likely not pretty-printed and it's hard to compare the output with the expected output.
|
||
|
|
|
||
|
|
### Local transformation (while developing)
|
||
|
|
|
||
|
|
Open the terminal at root directory and run the codemod to test the transformation, for example, testing the `accordion-props` codemod:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
node packages/mui-codemod/codemod deprecations/accordion-props packages/mui-codemod/src/deprecations/accordion-props/test-cases/theme.actual.js
|
||
|
|
```
|
||
|
|
|
||
|
|
### CI (after opening a PR)
|
||
|
|
|
||
|
|
To simulate a consumer-facing experience on any project before merging the PR, open the CodeSandbox CI build and copy the link from the "Local Install Instructions" section.
|
||
|
|
|
||
|
|
Run the codemod to test the transformation:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npx @mui/codemod@<link> <codemod> <path>
|
||
|
|
```
|
||
|
|
|
||
|
|
For example:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npx @mui/codemod@https://pkg.csb.dev/mui/material-ui/commit/39bf9464/@mui/codemod deprecations/accordion-props docs/src/modules/brandingTheme.ts
|
||
|
|
```
|