|
1 | | -# Contributing |
| 1 | +# Contributing to Node.js Userland Migration |
2 | 2 |
|
3 | | -A recipe generally has a few things: |
| 3 | +Thank you for your interest in contributing to this project! We value contributions from the community and want to make the process as smooth as possible. |
4 | 4 |
|
5 | | -* A `README.md` explaining its purpose and use (including any options, and required and optional |
6 | | -files). |
7 | | -* Tests via node's test runner (min coverage: 80%) |
8 | | - * unit tests |
9 | | - * end-to-end test(s) for accepted use-cases |
10 | | - * a `test` command in `package.json`; there may be sub-commands like `test:unit` & `test:e2e`, but there must be a parent that combines them. |
11 | | - * Include `--import='@nodejs/codemod-utils/snapshots` to standardise the filename (`${original_base_name}.snap.cjs`) across recipes. |
12 | | - * Ensure `--test-coverage-include` and `--test-coverage-exclude` are set correctly for the recipe's workspace. The root repo handles setting coverage rules like minimum line coverage. |
13 | | -* Code comments (js docs, etc) |
14 | | -* Types (either via typescript or jsdoc) |
| 5 | +## Getting Started |
15 | 6 |
|
16 | | -CI will run lint & type checking and all included test files against all PRs. |
| 7 | +### Prerequisites |
17 | 8 |
|
18 | | -New recipes are added under `./recipes` in their own folder, succinctly named for what they do. General-purpose recipes have simple names like `correct-ts-specifiers`. A suite of migrations has a name like `migrate from 18 to 20`, and more specific migrations are named like `migrate-fs-readFile-from-18-to-20`. |
| 9 | +Before you begin, ensure you have the current versions of the following installed: |
19 | 10 |
|
20 | | -## Before pushing a commit |
| 11 | +- node |
| 12 | +- npm |
21 | 13 |
|
22 | | -A convenient superset of checks is available via `node --run pre-commit`, which automatically fixes formatting and linting issues (that are safe to fix), checks types, and runs tests. Changes resulting from this should be committed. |
| 14 | +### Project Overview |
| 15 | + |
| 16 | +Our codebase is organized as follows: |
| 17 | + |
| 18 | +- `.github/`: Contains GitHub files like issue templates and workflows |
| 19 | +- `recipes/`: Contains all the codemods |
| 20 | +- `utils/`: An npm workspace with utility functions used by the codemods (including [ast-grep](https://ast-grep.github.io/) utilities) |
| 21 | + |
| 22 | +## Codemod Development |
| 23 | + |
| 24 | +### Structure of a Codemod |
| 25 | + |
| 26 | +Each codemod resides in its own directory under `recipes/` and should include: |
| 27 | + |
| 28 | +| File | Purpose | |
| 29 | +|------|---------| |
| 30 | +| `README.md` | Description, purpose, and usage instructions | |
| 31 | +| `package.json` | Package manifest | |
| 32 | +| `src/workflow.ts` | Main entry point using the `jssg` codemod API | |
| 33 | +| `codemod.yml` | Codemod manifest file | |
| 34 | +| `workflow.yml` | Workflow definition file | |
| 35 | +| `tests/` | Test suite using `jssg` testing utilities | |
| 36 | +| `tsconfig.json` | TypeScript configuration | |
| 37 | + |
| 38 | +### Example Files |
| 39 | + |
| 40 | +**`src/workflow.ts` example:** |
| 41 | +```ts |
| 42 | +import type { SgRoot, Edit } from "@codemod.com/jssg-types/main"; |
| 43 | +/** |
| 44 | + * Transform function that converts deprecated api.fn calls |
| 45 | + * to the new api.fn syntax. |
| 46 | + * |
| 47 | + * Handles: |
| 48 | + * 1. api.fn(<args>) |
| 49 | + * 2. api.fn(<args>, { recursive: true }) |
| 50 | + * ... |
| 51 | + */ |
| 52 | +export default function transform(root: SgRoot): string | null { |
| 53 | + const rootNode = root.root(); |
| 54 | + let hasChanges = false; |
| 55 | + const edits: Edit[] = []; |
| 56 | + // do some transformation |
| 57 | + if (!hasChanges) return null; |
| 58 | + return rootNode.commitEdits(edits); |
| 59 | +} |
| 60 | +``` |
| 61 | + |
| 62 | +**`codemod.yml` example:** |
| 63 | +```yaml |
| 64 | +schema_version: "1.0" |
| 65 | +name: "@nodejs/<codemod-name>" |
| 66 | +version: 1.0.0 |
| 67 | +description: <Your codemod description> |
| 68 | +author: <Your Name> |
| 69 | +license: MIT |
| 70 | +workflow: workflow.yaml |
| 71 | +category: migration |
| 72 | + |
| 73 | +targets: |
| 74 | + languages: |
| 75 | + - javascript |
| 76 | + - typescript |
| 77 | + |
| 78 | +keywords: |
| 79 | + - transformation |
| 80 | + - migration |
| 81 | + |
| 82 | +registry: |
| 83 | + access: public |
| 84 | + visibility: public |
| 85 | +``` |
| 86 | +
|
| 87 | +## Useful Resources |
| 88 | +
|
| 89 | +- [Codemod CLI Reference](https://docs.codemod.com/cli/cli-reference) |
| 90 | +- [Codemod Workflow Documentation](https://docs.codemod.com/cli/workflows) |
| 91 | +- [Codemod Studio Documentation](https://docs.codemod.com/codemod-studio) |
| 92 | +- [JS ast-grep (jssg) API reference](https://docs.codemod.com/cli/cli-reference#cli-command-reference) |
| 93 | +- [ast-grep Documentation](https://ast-grep.github.io/) |
| 94 | +
|
| 95 | +## Development Workflow |
| 96 | +
|
| 97 | +### Before Pushing a Commit |
| 98 | +
|
| 99 | +Run our comprehensive check suite: |
| 100 | +
|
| 101 | +```bash |
| 102 | +node --run pre-commit |
| 103 | +``` |
| 104 | + |
| 105 | +This will: |
| 106 | +- Fix formatting and safe linting issues automatically |
| 107 | +- Check types |
| 108 | +- Run tests |
| 109 | +Be sure to commit any changes resulting from these automated fixes. |
23 | 110 |
|
24 | 111 | > [!WARNING] |
25 | | -> Some integration tests modify fixtures because they run the entire codemod. Remember to use the `git restore` command to restore these files before pushing a commit. |
| 112 | +> Some integration tests modify fixtures as they run the entire codemod. Remember to use `git restore` to revert these files before committing. |
| 113 | +
|
| 114 | +### Commit Messages |
| 115 | + |
| 116 | +Please follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification for your commit messages. This helps with: |
| 117 | + |
| 118 | +- Automatic changelog generation |
| 119 | +- Understanding the history of changes |
| 120 | +- Semantic versioning |
| 121 | + |
| 122 | +Format: |
| 123 | +``` |
| 124 | +<type>(<scope>): <description> |
| 125 | +``` |
| 126 | + |
| 127 | +- **`type`**: The type of change (e.g., `feat`, `fix`, `docs`, `chore`, etc.) |
| 128 | +- **`scope`**: A short, lowercase description of the section of the codebase affected (e.g., `tmpDir-to-tmpdir`, `esm-migration`) |
| 129 | +- **`description`**: A concise summary of the change |
| 130 | + |
| 131 | +Examples: |
| 132 | +- `feat(tmpDir-to-tmpdir): add new node.js 18 migration codemod` |
| 133 | +- `fix(esm-migration): correct type checking in ESM migration` |
| 134 | +- `docs(codemod-usage): improve usage examples` |
| 135 | + |
| 136 | +## Pull Request Process |
| 137 | + |
| 138 | +When submitting a pull request: |
| 139 | +1. Ensure your changes are well-documented |
| 140 | +2. Run all tests (`node --run pre-commit`) |
| 141 | +3. Follow the project's coding standards |
| 142 | +4. Use the [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/) format in your PR title and description |
| 143 | +5. Link to any related issues, using [GitHub keywords](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests) where applicable. |
| 144 | + |
| 145 | +### Acceptance Criteria |
| 146 | + |
| 147 | +For a pull request to be merged, it must: |
| 148 | +- Receive approval from at least 2 reviewers |
| 149 | +- Pass all tests |
| 150 | +- Be open for at least 48 hours to allow for review and discussion |
| 151 | + - except hotfixes and trivial corrections (like typos) |
| 152 | + |
| 153 | +### Developer's Certificate of Origin 1.1 |
| 154 | + |
| 155 | +``` |
| 156 | +By contributing to this project, I certify that: |
| 157 | +
|
| 158 | +- (a) The contribution was created in whole or in part by me and I have the right to |
| 159 | + submit it under the open source license indicated in the file; or |
| 160 | +- (b) The contribution is based upon previous work that, to the best of my knowledge, |
| 161 | + is covered under an appropriate open source license and I have the right under that |
| 162 | + license to submit that work with modifications, whether created in whole or in part |
| 163 | + by me, under the same open source license (unless I am permitted to submit under a |
| 164 | + different license), as indicated in the file; or |
| 165 | +- (c) The contribution was provided directly to me by some other person who certified |
| 166 | + (a), (b) or (c) and I have not modified it. |
| 167 | +- (d) I understand and agree that this project and the contribution are public and that |
| 168 | + a record of the contribution (including all personal information I submit with it, |
| 169 | + including my sign-off) is maintained indefinitely and may be redistributed consistent |
| 170 | + with this project or the open source license(s) involved. |
| 171 | +
|
| 172 | +``` |
0 commit comments