Scaffold runbook docs

README.md

@@ -142,6 +142,7 @@ This container can be reached from your localhost (e.g. `redis://localhost:6379`
 
 ## Documentation (WIP)
 
+- [Template Migration](docs/template-migration/README.md)
 - [Code Guidelines](READMEs/code-guidelines.md)
 - [Testing](READMEs/testing.md)
 - [TypeScript](READMEs/typescript.md)

docs/template-migration/README.md

@@ -0,0 +1,33 @@
+# Template Migration
+
+So you wanna migrate a template, do ya? Well, I've got good news! You've come to the right place.
+
+This document outlines the process for migrating templates from the old `content-build` to `next-build`, complete with phase definitions, RACI matrices, and transition criteria.
+
+> [!NOTE]
+> 🏗️ This document is still a work in progress. As you work through the phases, if you see something that could be improved, please create a PR to update our docs!
+
+## Prerequisites
+
+- A successful build in `content-build`
+- A successful build in `next-build`
+
+## Phases
+
+The migration of templates consists of four distinct phases. When you get to the end, the template should be fully migrated, in production, and handed off to the Product-owning Team. Congratulations!
+
+Follow the links below to learn more about each phase:
+
+1. [Pre-Migration](./phases/pre-migration.md)
+   - **Definition**: The template for a given content type either doesn’t exist in next-build or is stale.
+2. [Active Migration](./phases/active-migration.md)
+   - **Definition**: The template is under active development & testing but has not yet been deployed to production.
+   - ⭐ This is where the bulk of the work happens.
+3. [Rollout](./phases/rollout.md)
+   - **Definition**: The template is now utilized to generate content in production.
+4. [Post-Launch](./phases/post-launch.md)
+   - **Definition**: The template is now in production awaiting handoff to the Product-owning Team.
+
+After the Post-Launch phase, the Product-owning Team has ownership of the template and is responsible for maintaining and enhancing the template.
+
+_Mission accomplished!_ 🎉

docs/template-migration/phases/active-migration.md

@@ -0,0 +1,53 @@
+# Template Migration: Active Migration
+
+## What is the Active Migration phase?
+
+A template is in the Active Migration phase when it's...y'know, under active development & testing but has not yet been deployed to production.
+
+_This is where the bulk of the work happens._
+
+## What do we do here?
+
+> [!NOTE]
+> 🏗️ We'll move some of this information into the how-to guides as we get them written.
+
+- The responsible team develops the new template in `next-build` to achieve parity with its current usage in production, including display, functionality and accessibility.
+  - The team is also responsible for all communication about decisions made around known/expected differences between the `next-build` and the `content-build` templates
+  - If there’s an intentional mismatch between the `content-build` and `next-build` output (the HTML created), a ticket must be created which answers the following questions:
+    - What is the difference?
+    - Why was the decision made to not have 1:1 parity with the content-build template on this particular element/item?
+    - Who signed off on the decision?
+    - When was the decision made?
+    - What is the impact to Veterans?
+    - Should this be addressed in the future?
+      - If no, the ticket can be closed and used only as a decision record for future reference
+- The responsible team completes full QA using the QA template
+
+## How do we do it?
+
+> [!IMPORTANT]
+> 🏗️ This is a high-level overview of the process. Each step will have its own documentation that you can reference for more detailed information. Coming soon to a PR near you!
+
+1. Find the template in `content-build`
+   - You'll use this to see the logic and structure to use in the `next-build` template
+1. Find a page that uses the template in `content-build`
+1. Create a new template in `next-build` to match the `content-build` template if one doesn't already exist
+1. Make the necessary changes to the `next-build` template to achieve parity with the `content-build` template
+1. Test the template in `next-build`
+   - Something about using the `FEATURE_NEXT_BUILD_CONTENT_ALL=true` environment variable
+1. Get QA approval
+
+## RACI
+
+- **Responsible:** CMS Team, Sitewide Team
+  - Determined by the team that commits to completing the work.
+  - Ownership is communicated to the CMS team by the committed team.
+- **Accountable:** Chris Valarida _(CMS Team)_
+- **Consulted:** Laura Flannery _(CMS Team)_
+- **Informed:** Any team not in the Responsible role
+
+## Transitioning to Rollout
+
+**Trigger**: The template achieves 1:1 parity with production or meets an agreed-upon snapshot baseline. (Determined by QA testing.)
+
+**Next step:** [Rollout](./rollout.md)

docs/template-migration/phases/post-launch.md

@@ -0,0 +1,38 @@
+# Template Migration: Post-Launch
+
+## What is the Post-Launch phase?
+
+The Post-Launch phase is the final phase of the template migration process. At this point, the template is used in production. Herein are the last few steps before the Product-owning Team takes over ownership of the template from the CMS Team.
+
+## What do we do here?
+
+- Removal of the old content-build templates 1 full sprint after a successful launch to production
+  - When: 1 full sprint after a successful launch to production
+  - Who: Owned exclusively by the CMS team, regardless of which team did the migration of the template
+  - What:
+    - Clear list of all content-build templates being replaced including all layouts and shared components
+    - Determine what the “content-build removal” entails:
+      - Query removal?
+      - CSS removal?
+      - Full Template/layout removal? Or just adding a comment at the top indicating that the layout should not be used and has been migrated to next-build?
+- Verification of prod behavior after content-build template removal
+  - Owned by the team migrating the template
+- Final handoff to the Product-owning Team
+
+## How do we do it?
+
+1. Verify the behavior of the template in production
+1. Create a PR to update the CODEOWNERS file, formalizing the handoff of accountability from the CMS Team to the Product-owning Team
+
+## RACI
+
+- **Responsible:** The CMS team & the team doing the migration
+- **Accountable:** Chris Valarida _(CMS Team)_
+- **Consulted:** Product-owning Team
+- **Informed:** Product-owning Team
+
+## Maintenance and Enhancements
+
+_Congratulations! You've made it!_
+
+The template is now in production and the Product-owning Team is responsible for maintaining and enhancing the template.

docs/template-migration/phases/pre-migration.md

@@ -0,0 +1,13 @@
+# Template Migration: Pre-Migration
+
+## What is the Pre-Migration phase?
+
+A template is in the Pre-Migration phase when it either doesn’t exist in `next-build` or is stale.
+
+_Nothing fancy here._
+
+## Transitioning to Active Migration
+
+**Trigger**: The template gets prioritized and assigned to a team.
+
+**Next step:** [Active Migration](./active-migration.md)

docs/template-migration/phases/rollout.md

@@ -0,0 +1,43 @@
+# Template Migration: Rollout
+
+## What is the Rollout phase?
+
+A template is in the Rollout phase when QA is complete and the template is ready to be utilized to generate content in production.
+
+## What do we do here?
+
+- Go / no go meeting for approval of cutover from content-build to next-build
+  - Required attendees include
+    - Erika Washburn
+    - Chris Valarida
+    - Laura Flannery
+    - Michelle Middaugh (optional)
+  - Eventually, this meeting will get replaced with async comms
+- Launch to production
+  - Task owned by CMS team, regardless of which team did the migration
+  - Exceptions to this ownership would need to be requested and discussed during the migration process
+
+## How do we do it?
+
+_Great question! We gon' fill this out!_ 😅
+
+- Something about using the `PAGE_RESOURCE_TYPES` environment variable
+
+## RACI
+
+- **Responsible:** CMS Team
+- **Accountable:** Chris Valarida _(CMS Team)_
+- **Consulted:**
+  - Tim Cosgrove
+  - Laura Flannery
+  - Product-owning Team
+- **Informed:**
+  - Help Desk
+  - Platform team
+  - Larger VA ecosystem comms _(ToT or #vfs-change-announcements channel)_
+
+## Transitioning to Post-Launch
+
+**Trigger:** The template is ready for post-launch verification.
+
+**Next step:** [Post-Launch](./post-launch.md)