Formalize email template repo process and train team on workflow

[scotwells]

Summary

Formalize how this repo (email templates used by Datum Cloud) is managed, and train other developers on the workflow, so that maintaining and releasing email templates isn't dependent on tribal knowledge.

Motivation

Currently the process for developing, reviewing, and releasing email templates lives mostly in the heads of a small number of contributors. This issue tracks the work to document that process, produce onboarding material, and get other team members comfortable operating independently in this repo.

Acceptance Criteria

• Repo publishes its own kustomize bundle: email-templates builds and publishes its own kustomize bundle (OCI artifact) instead of generating YAML and opening an automated PR against datum-cloud/datum.
• infra deploys directly from this repo: infra#3593 (merged) points production/preview at real vX.Y.Z release tags instead of the interim main-build-tag pin used since the bundle cutover; staging still deliberately tracks main builds. Verified with a real release (v1.0.0) actually publishing a matching OCI bundle end-to-end.
• This repo is actually versioned: Real releases/tags, cut via a one-click "Publish New Version" workflow anyone on the GTM team can run — no engineering involvement needed. Tested live: found and fixed two bugs in the workflow (#74) — it ignored the chosen bump on a first release, and it wasn't actually publishing a bundle for the release it created. v1.0.0 is now live and confirmed working.
• Promotion/review gate defined: The GTM team reviews and merges email content/template changes directly, without needing engineering sign-off — enforced via CODEOWNERS (#30, merged).
• Release process documented: RELEASING.md walks through publishing a new version in plain language (which button to click, what patch/minor/major mean, that production rollout takes a few minutes) — no engineering background assumed.
• Wiki guides produced: Transactional Emails guide published under Customer Success, covering how to request a change, who reviews/merges it, and how to publish a release — written for a non-technical audience, with links out to CONTRIBUTING.md/RELEASING.md for anyone who wants the engineering detail.
• Development environment verified: Brought up .devcontainer from a clean clone and confirmed postCreateCommand, pnpm dev/generate:all/check/screenshot all work. Found and fixed a real gap: react-email and @react-email/ui had drifted to mismatched versions, which made pnpm dev hang on an interactive prompt in any non-interactive environment (#75, merged).
• Team training completed: Walk at least one other team member through the full workflow (setup, making a change, previewing, releasing) and confirm they can complete it independently.

Also delivered (beyond original scope)

• Non-technical stakeholders can request a change themselves: two issue forms (Content/Wording Change, New Email Template) let anyone describe a request in plain language — no code, no repo access needed.
• Requests are drafted automatically: an AI assistant reads the request and opens a ready-to-review PR for template changes, addressing routine requests without engineering having to pick them up.
• PRs are reviewable without technical background: PR descriptions and issue updates are written in plain language (before/after wording, what the email says), with implementation detail tucked away for engineers who want it.
• Reviewers see the actual email, not just code: a screenshot of the rendered template posts automatically to the PR, so reviewers can judge the real result without running anything locally.
• Reference examples for requesters: example issues (#63 for a content change, #64 for a new template) show what a well-filled-out request looks like, linked from the wiki guide.
• Known-vulnerable dependencies cleaned up: resolved the ws/esbuild Dependabot alerts (#73) by refreshing the lockfile; the remaining postcss alert is tracked separately, pending an upstream React Email fix.

[scotwells]

Quick update on direction: we want this repo to own its own path to production instead of routing changes through datum. Concretely, email-templates will publish its own kustomize bundle, and infra will point a Flux Kustomization directly at it — no more auto-generated PR into datum, no more piggybacking on datum's release cadence.

Why this is better for us: one less hop that a template fix can get stuck in unnoticed, our own release cadence instead of waiting on an unrelated datum release, and a clean answer to "what's live in prod right now" once we start actually versioning releases here (something we don't do today). We'll still want a review/promotion gate, just one that lives here instead of relying on someone catching a bot PR in a different repo.

This changes what the acceptance criteria above are describing — same goals, new process. To get there we'll need to: add versioning/releases to this repo, set up the new OCIRepository/Kustomization in infra, remove the old auto-PR-into-datum workflow, and write up the new flow (including staging vs. production promotion) as the release doc this issue is tracking.

[scotwells]

Here's the checklist for getting us to the new process:

Publish our own bundle

• Generate our kustomize bundle from this repo (config/email-templates/) instead of exporting YAML for a bot PR into datum (#19)
• Add a workflow here that publishes that bundle on merge to main and on release (#19)

Give this repo real versions

• Start tagging releases here so there's a clear answer to "what's live in prod" (#20) — verified live: v1.0.0 is cut and its OCI bundle is published (#74 fixed two bugs the first real run surfaced).

Wire up infra

• Point infra at our new bundle directly (new source + deployment config) (infra#3504)
• Set up per-environment promotion: staging auto-updates, preview/production are pinned and promoted deliberately (infra#3504) — production/preview now track real release tags only (infra#3593, merged), replacing the interim main-build-tag pin.

Cut over safely (no dropped templates)

• Temporarily stop the old deployment path from deleting anything when we unhook it, so templates already live in the system aren't removed mid-cutover (datum-cloud/infra#3503)
• Switch every environment over to the new source (infra#3517 — done as one combined change instead of staged per-environment, since prune being off already covered the risk that staging was meant to protect against; applied cleanly)
• Snapshot what's currently deployed in each environment first — not needed once pruning was already off; nothing to fall back to

Clean up the old path

• Retire the old bot-PR workflow (#22)
• Retire the now-unused config in datum (datum#263)

Document and train

• Write up the new release process (#21, merged) — rewritten for a non-technical audience: which button to click, what patch/minor/major mean, and that rollout takes a few minutes.
• Publish wiki guides for creating/updating templates and submitting changes (wiki#18, merged) — lives under Customer Success, covers requesting a change, who reviews/merges, and how to release.
• Confirm the local dev setup works end-to-end on a clean machine — found and fixed two real gaps: a lint failure on a clean checkout (#25) and a known pnpm build failure now documented in CONTRIBUTING.md
• Confirm the setup also works through .devcontainer (fresh container, not just a clean machine) — found and fixed a real version-mismatch bug that hung pnpm dev non-interactively (#75, merged)
• Walk a teammate through the whole flow and confirm they can run it solo

Extras that came out of this work

• Non-technical README + CONTRIBUTING.md split (#24)
• Template screenshots committed to PR branches, visible in the README (#29, merged)
• Route code ownership to datum-cloud/gtm (#30, merged)
• Non-technical stakeholders can request changes themselves via GitHub issue forms, with an AI assistant auto-drafting a reviewable PR — no engineering pickup needed for routine content/template requests (#40 and follow-ups)
• PR descriptions and issue updates written in plain language for GTM reviewers, with technical detail collapsed for engineers (#60)
• Reference example issues showing what a well-filled-out request looks like (#63, #64)
• Resolved known-vulnerable dependencies (ws/esbuild Dependabot alerts) (#73)