Skip to main content

Guiding principles

There are several guiding principles we follow in this project.

Codemods should target a version of package

Code is always on the move and codemods written against a specific API, at a specific point of time aren't guaranteed to work into the future. That's why we should aim to limit the scope of a codemod to migrate a specific package from one API to another.

In doing so:

  • The scope and intent of a codemod is encoded and always obvious to users.
  • Changes to the package that occur thereafter should not affect or break older codemods.
  • Allow us to go back and patch older codemods if necessary.

Conversely, if codemods were named arbitrarily, there will be no apparent sequence for the consumer to follow.

Codemods should be playable in sequence

By writing codemods that target a package and version, it should then be theoretically possible to move your consumers across multiple major versions by playing them in a sequence. For example, migrating from an older version of @mylib/button to the latest is possible by playing all available codemods in order v14 -> v15 -> v16.

Ultimately, this is the happy-path this project strives for. But it's also important to acknowledge that in reality this is not always be possible, depending on the migration path and how hard it might be to write a codemods for it. In these cases we recommend that you are aware of when not to codemod and what to do when a codemod isn't possible.

Codemods should do as much as can be safely done automatically or prompt for human intervention

Writing a codemod to completely migrate a package from one working state to another is not always feasible. Some edge cases might simply be too hard to support. When this is the case, bailing out and prompting for human intervention should be your first fallback. This gives consumers a chance to review the changes of the codemod, read the prompts containing context about the changes they need to action and make the remaining manual steps as painless and straight forward as possible.

For more information, please see the Prompting for human input guide.