From 7e0fa1b1a923fc128a88ba4cf34b8258f9d14527 Mon Sep 17 00:00:00 2001 From: Chris Valarida Date: Wed, 12 Feb 2025 16:30:21 -0800 Subject: [PATCH 1/6] First pass at scaffolding the runbook It actually contains mostly the same information as is in that Canvas right now, but I think that's okay? Navigation is easy, and that's the biggest thing. --- docs/template-migration/README.md | 29 +++++++++++++ docs/template-migration/active-migration.md | 46 +++++++++++++++++++++ docs/template-migration/post-launch.md | 38 +++++++++++++++++ docs/template-migration/pre-migration.md | 13 ++++++ docs/template-migration/rollout.md | 43 +++++++++++++++++++ 5 files changed, 169 insertions(+) create mode 100644 docs/template-migration/README.md create mode 100644 docs/template-migration/active-migration.md create mode 100644 docs/template-migration/post-launch.md create mode 100644 docs/template-migration/pre-migration.md create mode 100644 docs/template-migration/rollout.md diff --git a/docs/template-migration/README.md b/docs/template-migration/README.md new file mode 100644 index 000000000..77210c6c4 --- /dev/null +++ b/docs/template-migration/README.md @@ -0,0 +1,29 @@ +# 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. Follow the links below to learn more about each phase: + +1. [Pre-Migration](./pre-migration.md) + - **Definition**: The template for a given content type either doesn’t exist in next-build or is stale. +2. [Active Migration](./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](./rollout.md) + - **Definition**: The template is now utilized to generate content in production. +4. [Post-Launch](./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. diff --git a/docs/template-migration/active-migration.md b/docs/template-migration/active-migration.md new file mode 100644 index 000000000..28c0f4c7d --- /dev/null +++ b/docs/template-migration/active-migration.md @@ -0,0 +1,46 @@ +# Template Migration: Active Migration + +## What is the Active Migration phase? + +A template is in the Active Migration phase when it is...y'know, under active development & testing but has not yet been deployed to production. + +## What do we do here? + +- 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 +1. Test the template in `next-build` + - Something about using the `FEATURE_NEXT_BUILD_CONTENT_ALL=true` environment variable + +## 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 team 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) diff --git a/docs/template-migration/post-launch.md b/docs/template-migration/post-launch.md new file mode 100644 index 000000000..85359725a --- /dev/null +++ b/docs/template-migration/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? + +- [ ] Verify the behavior of the template in production +- [ ] 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 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. diff --git a/docs/template-migration/pre-migration.md b/docs/template-migration/pre-migration.md new file mode 100644 index 000000000..280096fc7 --- /dev/null +++ b/docs/template-migration/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) diff --git a/docs/template-migration/rollout.md b/docs/template-migration/rollout.md new file mode 100644 index 000000000..358bcc899 --- /dev/null +++ b/docs/template-migration/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) From e9994b23b63c33032b2a56e127018abaab548de0 Mon Sep 17 00:00:00 2001 From: Chris Valarida Date: Wed, 12 Feb 2025 16:32:24 -0800 Subject: [PATCH 2/6] nest in phases/ --- docs/template-migration/README.md | 8 ++++---- docs/template-migration/{ => phases}/active-migration.md | 0 docs/template-migration/{ => phases}/post-launch.md | 4 ++-- docs/template-migration/{ => phases}/pre-migration.md | 0 docs/template-migration/{ => phases}/rollout.md | 0 5 files changed, 6 insertions(+), 6 deletions(-) rename docs/template-migration/{ => phases}/active-migration.md (100%) rename docs/template-migration/{ => phases}/post-launch.md (88%) rename docs/template-migration/{ => phases}/pre-migration.md (100%) rename docs/template-migration/{ => phases}/rollout.md (100%) diff --git a/docs/template-migration/README.md b/docs/template-migration/README.md index 77210c6c4..393e72f5a 100644 --- a/docs/template-migration/README.md +++ b/docs/template-migration/README.md @@ -16,14 +16,14 @@ This document outlines the process for migrating templates from the old `content The migration of templates consists of four distinct phases. Follow the links below to learn more about each phase: -1. [Pre-Migration](./pre-migration.md) +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](./active-migration.md) +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](./rollout.md) +3. [Rollout](./phases/rollout.md) - **Definition**: The template is now utilized to generate content in production. -4. [Post-Launch](./post-launch.md) +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. diff --git a/docs/template-migration/active-migration.md b/docs/template-migration/phases/active-migration.md similarity index 100% rename from docs/template-migration/active-migration.md rename to docs/template-migration/phases/active-migration.md diff --git a/docs/template-migration/post-launch.md b/docs/template-migration/phases/post-launch.md similarity index 88% rename from docs/template-migration/post-launch.md rename to docs/template-migration/phases/post-launch.md index 85359725a..9a520e1f1 100644 --- a/docs/template-migration/post-launch.md +++ b/docs/template-migration/phases/post-launch.md @@ -21,8 +21,8 @@ The Post-Launch phase is the final phase of the template migration process. At t ## How do we do it? -- [ ] Verify the behavior of the template in production -- [ ] Create a PR to update the CODEOWNERS file, formalizing the handoff of accountability from the CMS Team to the Product-owning Team +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 diff --git a/docs/template-migration/pre-migration.md b/docs/template-migration/phases/pre-migration.md similarity index 100% rename from docs/template-migration/pre-migration.md rename to docs/template-migration/phases/pre-migration.md diff --git a/docs/template-migration/rollout.md b/docs/template-migration/phases/rollout.md similarity index 100% rename from docs/template-migration/rollout.md rename to docs/template-migration/phases/rollout.md From c81daa394d34a6debcf4177e76612ff329923256 Mon Sep 17 00:00:00 2001 From: Chris Valarida Date: Wed, 12 Feb 2025 16:37:47 -0800 Subject: [PATCH 3/6] Add a link from the root README --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index ee5639e97..52675e830 100644 --- a/README.md +++ b/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) From afd2de0c0dde26e14961ef9e52669b81c1921ab1 Mon Sep 17 00:00:00 2001 From: Chris Valarida Date: Wed, 12 Feb 2025 16:43:14 -0800 Subject: [PATCH 4/6] Typo fix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Carried over from the Canvas. 🤷♂️ --- docs/template-migration/phases/active-migration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/template-migration/phases/active-migration.md b/docs/template-migration/phases/active-migration.md index 28c0f4c7d..ba0807c52 100644 --- a/docs/template-migration/phases/active-migration.md +++ b/docs/template-migration/phases/active-migration.md @@ -29,12 +29,13 @@ A template is in the Active Migration phase when it is...y'know, under active de 1. Create a new template in `next-build` to match 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 team committed team. + - 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 From 32421590efe0d5a80fc453f6a452502202c3fcd1 Mon Sep 17 00:00:00 2001 From: Chris Valarida Date: Wed, 12 Feb 2025 16:50:55 -0800 Subject: [PATCH 5/6] Some edits for voice and clarity --- docs/template-migration/README.md | 6 +++++- docs/template-migration/phases/active-migration.md | 7 ++++++- docs/template-migration/phases/pre-migration.md | 6 +++--- 3 files changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/template-migration/README.md b/docs/template-migration/README.md index 393e72f5a..d19264c76 100644 --- a/docs/template-migration/README.md +++ b/docs/template-migration/README.md @@ -14,7 +14,9 @@ This document outlines the process for migrating templates from the old `content ## Phases -The migration of templates consists of four distinct phases. Follow the links below to learn more about each phase: +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. @@ -27,3 +29,5 @@ The migration of templates consists of four distinct phases. Follow the links be - **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!_ 🎉 diff --git a/docs/template-migration/phases/active-migration.md b/docs/template-migration/phases/active-migration.md index ba0807c52..9ff3cf84f 100644 --- a/docs/template-migration/phases/active-migration.md +++ b/docs/template-migration/phases/active-migration.md @@ -2,10 +2,15 @@ ## What is the Active Migration phase? -A template is in the Active Migration phase when it is...y'know, under active development & testing but has not yet been deployed to production. +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: diff --git a/docs/template-migration/phases/pre-migration.md b/docs/template-migration/phases/pre-migration.md index 280096fc7..a13f25b4c 100644 --- a/docs/template-migration/phases/pre-migration.md +++ b/docs/template-migration/phases/pre-migration.md @@ -1,8 +1,8 @@ -# Template Migration: Pre-migration +# Template Migration: Pre-Migration -## What is the Pre-migration phase? +## 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. +A template is in the Pre-Migration phase when it either doesn’t exist in `next-build` or is stale. _Nothing fancy here._ From 845f05bf0efd705ac9e715b99e82bc48b7e710eb Mon Sep 17 00:00:00 2001 From: Chris Valarida Date: Thu, 13 Feb 2025 14:23:16 -0800 Subject: [PATCH 6/6] Resolve Laura's feedback --- docs/template-migration/phases/active-migration.md | 3 ++- docs/template-migration/phases/post-launch.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/template-migration/phases/active-migration.md b/docs/template-migration/phases/active-migration.md index 9ff3cf84f..4da1bcfcb 100644 --- a/docs/template-migration/phases/active-migration.md +++ b/docs/template-migration/phases/active-migration.md @@ -31,7 +31,8 @@ _This is where the bulk of the work happens._ 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 +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 diff --git a/docs/template-migration/phases/post-launch.md b/docs/template-migration/phases/post-launch.md index 9a520e1f1..2b348696a 100644 --- a/docs/template-migration/phases/post-launch.md +++ b/docs/template-migration/phases/post-launch.md @@ -26,7 +26,7 @@ The Post-Launch phase is the final phase of the template migration process. At t ## RACI -- **Responsible:** The team doing the migration +- **Responsible:** The CMS team & the team doing the migration - **Accountable:** Chris Valarida _(CMS Team)_ - **Consulted:** Product-owning Team - **Informed:** Product-owning Team