From 0fb966bdac1824afe57d12630e6a15ef053d72bb Mon Sep 17 00:00:00 2001 From: Jack Howard Date: Fri, 22 Aug 2025 12:19:16 -0700 Subject: [PATCH 1/4] docs: add metaprogramming section with automation rules and nav link --- docs/automation/intro.mdx | 6 ++++++ docusaurus.config.js | 7 +++++++ 2 files changed, 13 insertions(+) create mode 100644 docs/automation/intro.mdx diff --git a/docs/automation/intro.mdx b/docs/automation/intro.mdx new file mode 100644 index 0000000..b347ccb --- /dev/null +++ b/docs/automation/intro.mdx @@ -0,0 +1,6 @@ +# Playbook + +## Rules + +- Do not do manual tasks, like formatting strings. For example, use functions to camelCase, kebab-case, or snake_case. If you do a tedious action like this once, it may feel like progress. But doing manual tasks weekly is not a sustainable practice. +- \ No newline at end of file diff --git a/docusaurus.config.js b/docusaurus.config.js index 7e11206..4b782e0 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -121,6 +121,13 @@ const config = { label: "Examples", href: "/docs/category/examples", }, + { + type: "docSidebar", + sidebarId: "tutorialSidebar", + position: "left", + label: "Metaprogramming", + href: "/docs/automation/intro", + }, { href: "https://github.com/JackHowa/ember-react-cheatsheet", label: "GitHub", From 2e4b22609bfff25d433a686b087b7d8d6de520dc Mon Sep 17 00:00:00 2001 From: Jack Howard Date: Fri, 22 Aug 2025 12:41:53 -0700 Subject: [PATCH 2/4] docs: add automation playbook tips for sustainable migrations --- docs/automation/intro.mdx | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/automation/intro.mdx b/docs/automation/intro.mdx index b347ccb..5ba20dc 100644 --- a/docs/automation/intro.mdx +++ b/docs/automation/intro.mdx @@ -1,6 +1,13 @@ # Playbook +For a sustainable and less tedious automated migration, here are a few general tips to follow: + ## Rules -- Do not do manual tasks, like formatting strings. For example, use functions to camelCase, kebab-case, or snake_case. If you do a tedious action like this once, it may feel like progress. But doing manual tasks weekly is not a sustainable practice. -- \ No newline at end of file +- Do not do manual tasks like formatting strings. For example, use functions to camelCase, kebab-case, snake_case, etc. If you do an action like this once, it may feel like progress. But doing manual string manipulation weekly is not a sustainable practice and is subject to typos. +- Do not do manual searches, like in VS Code or GitHub.com. Use Abstract Syntax Trees that understand code context (e.g., code comments) to find code via running a script. Typing into VS Code or GitHub.com is subject to typos, similarly. Also, the search is dependent upon their systems for finding code, including any API issues or local settings (e.g., ignoring file types). +- Do not run scripts via node or bash directly. Instead run via npm commands. `npm run migrate` takes less time to type than `node ./path-to-script/really-long-folder-name/really-long-file-name.js`. Plus, npm commands can use [lifecycle scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts#life-cycle-scripts) like `postmigrate` scripts like Prettier to run after the migration. Running scripts this way is more powerful and repeatedable. +- Do look for unused code first and remove it. For Ember, you can use my fork of [ember-unused-components](https://github.com/JackHowa/ember-unused-components) to find unused components and addons. +- Do not rely upon git for lines of code migrated. Use AST-aware tools to count lines of actual code migrated, like [scc](https://github.com/boyter/scc). git can also be inaccurate if parent lines of code are deleted or added, affecting child ones. Run checks on a regular basis to see progress in a repeatable, quick way. +- Do not feel pressured to go in and review every single PR on your team checking for compliance to migration rules. Use [Danger.js](https://danger.systems/js/) or GitHub Actions to automatically check for compliance to rules. (This can also report to Slack for company-wide visibility.) +- Do use IDE-wide prompts like repo-level [Windsurf rules](https://windsurf.com/editor/directory) to enable compliance to migration rules. \ No newline at end of file From fbcd498830412b0a8185512e689cafb285770b92 Mon Sep 17 00:00:00 2001 From: Jack Howard Date: Fri, 22 Aug 2025 12:54:12 -0700 Subject: [PATCH 3/4] docs: add AST Explorer and example files tips for codebase migration --- docs/automation/intro.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/automation/intro.mdx b/docs/automation/intro.mdx index 5ba20dc..fc59bc4 100644 --- a/docs/automation/intro.mdx +++ b/docs/automation/intro.mdx @@ -10,4 +10,7 @@ For a sustainable and less tedious automated migration, here are a few general t - Do look for unused code first and remove it. For Ember, you can use my fork of [ember-unused-components](https://github.com/JackHowa/ember-unused-components) to find unused components and addons. - Do not rely upon git for lines of code migrated. Use AST-aware tools to count lines of actual code migrated, like [scc](https://github.com/boyter/scc). git can also be inaccurate if parent lines of code are deleted or added, affecting child ones. Run checks on a regular basis to see progress in a repeatable, quick way. - Do not feel pressured to go in and review every single PR on your team checking for compliance to migration rules. Use [Danger.js](https://danger.systems/js/) or GitHub Actions to automatically check for compliance to rules. (This can also report to Slack for company-wide visibility.) -- Do use IDE-wide prompts like repo-level [Windsurf rules](https://windsurf.com/editor/directory) to enable compliance to migration rules. \ No newline at end of file +- Do use IDE-wide prompts like repo-level [Windsurf rules](https://windsurf.com/editor/directory) to enable compliance to migration rules. +- Do use example files or example folders. Do not test on the whole codebase or group of targets. Look for and isolate problems and fix them. This minimizes the time spent watching your metaprogramming run. This is for your sanity but also for quick iteration and reproducibility. Having difficult migrations as well as easier ones works a little bit like testing. Putting these test files in your codemods folder can be useful along with the expected output in a similar file. There isn't a metaprogramming test framework that I know of... +- Do use AST Explorer ([demo](https://astexplorer.net/)) to test your metaprogramming and learn about Abstract Syntax Trees. (Shoutout Kent C. Dodds for showing this in a [Frontend Masters course](https://frontendmasters.com/courses/linting-asts/).) +- Do \ No newline at end of file From 6378f14342a7acf3b6a9d9a24198de63d14e806a Mon Sep 17 00:00:00 2001 From: Jack Howard Date: Fri, 22 Aug 2025 12:54:26 -0700 Subject: [PATCH 4/4] docs: remove empty bullet point from automation intro --- docs/automation/intro.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/automation/intro.mdx b/docs/automation/intro.mdx index fc59bc4..e8a4776 100644 --- a/docs/automation/intro.mdx +++ b/docs/automation/intro.mdx @@ -12,5 +12,4 @@ For a sustainable and less tedious automated migration, here are a few general t - Do not feel pressured to go in and review every single PR on your team checking for compliance to migration rules. Use [Danger.js](https://danger.systems/js/) or GitHub Actions to automatically check for compliance to rules. (This can also report to Slack for company-wide visibility.) - Do use IDE-wide prompts like repo-level [Windsurf rules](https://windsurf.com/editor/directory) to enable compliance to migration rules. - Do use example files or example folders. Do not test on the whole codebase or group of targets. Look for and isolate problems and fix them. This minimizes the time spent watching your metaprogramming run. This is for your sanity but also for quick iteration and reproducibility. Having difficult migrations as well as easier ones works a little bit like testing. Putting these test files in your codemods folder can be useful along with the expected output in a similar file. There isn't a metaprogramming test framework that I know of... -- Do use AST Explorer ([demo](https://astexplorer.net/)) to test your metaprogramming and learn about Abstract Syntax Trees. (Shoutout Kent C. Dodds for showing this in a [Frontend Masters course](https://frontendmasters.com/courses/linting-asts/).) -- Do \ No newline at end of file +- Do use AST Explorer ([demo](https://astexplorer.net/)) to test your metaprogramming and learn about Abstract Syntax Trees. (Shoutout Kent C. Dodds for showing this in a [Frontend Masters course](https://frontendmasters.com/courses/linting-asts/).) \ No newline at end of file