Migration map from how-we-work

Where every page of the old repository ended up, and what changed on the way

This repository replaces newfold-labs/how-we-work, which was 33 flat markdown files numbered by reading order.

how-we-work is not archived. It keeps publishing a redirect shim so old URLs still resolve, because GitHub does not redirect project Pages URLs across repositories and jekyll-redirect-from only covers path changes inside a single site.

Where everything went

Documents that were split

Roughly a quarter of the old content was process rather than standards. Mixing the two meant the repository had no way to express that “ask your team lead for access” is not something a check can score you against.

3.2-files-directories.md

• General file and directory rules, plus the WordPress class- prefix note, to general/naming-files-directories.md
• Brand Plugins section to artifacts/plugin/structure.md
• Modules section to artifacts/module/structure.md

9-version-control.md

• GitFlow, branch naming and the CI stage table to general/git.md
• Tagging, semver and pre-release conventions to general/releases.md
• Code review and release restrictions to process/code-review.md

10-releases.md

• Cadence and version semantics to general/releases.md
• Compatibility, which duplicated 5-wordpress.md, merged into platform/wordpress/support-matrix.md
• Jira planning, release flow, rollback and the release lead checklist to process/release-runbook.md

12-tests.md

• Test types and assertion guidance to general/testing.md
• Module Cypress conventions to artifacts/module/testing.md

What changed in the content

Migration was not a straight copy. Beyond adding front matter to all 43 resulting documents and merging the six existing title-only blocks:

Broken links fixed. The old README linked to 6-laravel.md, deleted in 2022. 11-module-development.md linked to a misspelled 13-architectural-reveiw.md. The table of contents omitted 3.5-naming-wp-hooks.md and 14-cloudflare-workers.md entirely. Internal links and their anchors are now validated in CI, so this class of rot cannot come back.

Liquid-hostile code samples fenced. The AI translation workflow document contains GitHub Actions expressions using ${{ ... }}. On the old site Liquid evaluated those as template variables and rendered them empty, so the published page showed a broken snippet. They are now wrapped in {% raw %} tags.

Spelling and grammar corrected throughout, without changing what any standard requires.

Line-number deep links removed. Several links pointed at specific line ranges in plugin and module source (#L266-L269). Line numbers drift, so these now point at the file.

Two truncated sentences. 5.5-wordpress-security.md ended a section mid-sentence at “It can be tempting to cache a WP_Query or $wpdb”; it now completes the thought about persisting database credentials. 4-frontend-best-practices.md had a bullet cut off at “Long-running operations without reliable way to predic”, which was dropped rather than guessed at.

5.10-wp-cli.md marked draft. It ends with an empty “Custom WP-CLI Commands” heading. Rather than migrate an unfinished document as though it were settled, it carries status: draft and is listed below.

Theme standards stubbed. No theme-specific content ever existed. artifacts/theme/structure.md is a draft stub listing what needs writing, so every artifact type has a home.

Content still to be written

0-SCRATCH.md in how-we-work was an untracked TODO list. It was not migrated, but the gaps it named are real and are recorded here so they are not lost a second time. Nothing below is tracked as an issue yet.

The two draft documents flip to active once written. The rest need an RFC first, per contributing.

Related

• Front matter schema

  Every field a standards document carries, what it means, and what CI checks

• Standard lifecycle

  What draft, active, deprecated and superseded mean, and why nothing is ever deleted