Search


Purpose

This plan converts the completed discovery work into an executable GCDS migration backlog. It defines phases, child-issue boundaries, dependencies, risk, completion criteria, and verification checkpoints.

The plan follows Decision 001 and Decision 002. Detailed evidence comes from the WET/GCWeb Dependency Inventory, Shared Template Inventory, WET-to-GCDS Component Map, No-Direct-Replacement Analysis, and GCDS Delivery Strategy.

Delivery Rules

JavaScript and Fallback Standard

GCDS web components require JavaScript to register custom elements, attach Shadow DOM, and provide their enhanced presentation and behavior. The migration does not require the fully enhanced interface to behave identically when JavaScript is disabled.

Instead, each work package must determine whether its essential content or task remains available before component upgrade or without JavaScript. Use native links, forms, headings, lists, tables, and visible text as the baseline where practical. When a GCDS component cannot provide a usable native fallback, document the affected task, impact, and approved exception rather than claiming no-JavaScript parity.

Common Definition of Done

Every child issue must meet these conditions unless its scope explains why a check does not apply:

Common Verification

Every implementation pull request must run:

Manual verification must cover the changed English and French states, keyboard operation, focus visibility, accessible names, and responsive reflow when relevant. Interactive work must also assess screen-reader behavior and its native or no-JavaScript baseline.

Phase and Dependency Summary

The following table lists the linear implementation order. Child issue numbers are assigned only after this backlog is approved and the issues are created.

Order Phase Proposed Child Issue Risk Depends On
1 Foundation Establish parallel GCDS foundation and preview fixture moderate Discovery acceptance
2 Shell Migrate header and global navigation group serious 1
3 Shell Migrate footer and contextual links moderate 2
4 Shell Complete and approve parallel page shell serious 3
5 Components Migrate notices and archived-content state serious 4
6 Components Migrate secondary navigation, downloads, and contribution UI moderate 5
7 Components Migrate landing, collection, update, and role templates moderate 6
8 Behavior Replace page-directory overlays with inline structure serious 7
9 Behavior Replace directory tag filtering with progressive enhancement serious 8
10 Behavior Replace enhanced directory table behavior serious 9
11 Behavior Replace clauses lightbox and WET footnotes with native references moderate 10
12 Behavior Remove or replace analytics chart enhancement moderate 11
13 Cleanup Migrate language-selection and not-found pages serious 12
14 Cleanup Migrate remaining inline content dependencies serious 13
15 Cleanup Activate GCDS default layout and remove legacy runtime critical 14
16 QA/Cutover Complete full-site QA and production cutover critical 15

Implementation remains sequential under Decision 002. Dependencies may be adjusted in the approved GitHub issue bodies only when doing so does not create concurrent feature branches or mix framework runtimes.

Phase 0: Discovery

Issues #771 through #776 form the Discovery phase.

Discovery Exit Gate

Phase 1: Foundation

Work Package 1: Establish Parallel GCDS Foundation and Preview Fixture

Proposed branch: feature/gcds-foundation

Purpose: Prove that GCDS can build and render independently without changing normal WET site output.

Scope:

Exclusions: Production layout changes, final header or footer design, content migration, and WET removal.

Dependencies and blockers: Discovery exit gate; exact package versions and supported import approach must be confirmed from official GCDS documentation.

Risk: moderate

Definition of done:

Specific verification:

Phase 2: Shell

Work Package 2: Migrate Header and Global Navigation Group

Proposed branch: feature/gcds-header

Purpose: Replace the global header as one coherent bilingual and keyboard-navigation unit.

Scope:

Exclusions: Footer, body grid, shared notices, page-family navigation, and changes to current WET header partials.

Dependencies and blockers: Work Package 1; official component APIs and slot composition must be confirmed for the pinned version.

Risk: serious

Definition of done:

Specific verification:

Proposed branch: feature/gcds-footer

Purpose: Replace the global footer while preserving bilingual contextual navigation.

Scope:

Exclusions: Contribution links outside the footer and removal of the WET footer.

Dependencies and blockers: Work Package 2; pinned footer API and content slots.

Risk: moderate

Definition of done:

Specific verification:

Work Package 4: Complete and Approve Parallel Page Shell

Proposed branch: feature/gcds-page-shell

Purpose: Complete the parallel shell milestone without making it the site default.

Scope:

Exclusions: Shared notices, page-family templates, complex behavior, content edits, and default-layout activation.

Dependencies and blockers: Work Package 3; design and accessibility reviewers must be available for milestone approval.

Risk: serious

Definition of done:

Specific verification:

Shell Exit Gate

Work Package 4 must record shell approval before component work begins. Any critical or serious shell finding blocks the next phase.

Phase 3: Components

Work Package 5: Migrate Notices and Archived-Content State

Proposed branch: feature/gcds-notices

Purpose: Replace static message and archived-state presentation without recreating unnecessary WET behavior.

Scope:

Exclusions: Sticky, dismissible, or animated archived banners unless new evidence and a separate approved scope justify them.

Dependencies and blockers: Work Package 4; supported notice variants in the pinned GCDS version.

Risk: serious

Definition of done:

Specific verification:

Work Package 6: Migrate Secondary Navigation, Downloads, and Contribution UI

Proposed branch: feature/gcds-secondary-ui

Purpose: Migrate reusable supporting interfaces while retaining native semantics and visible information.

Scope:

Exclusions: Landing-page groups, directories, tables, and content-file icon markup.

Dependencies and blockers: Work Package 5; confirmed GCDS icon availability and Office navigation pattern.

Risk: moderate

Definition of done:

Specific verification:

Work Package 7: Migrate Landing, Collection, Update, and Role Templates

Proposed branch: feature/gcds-page-families

Purpose: Replace recurring GCWeb and Bootstrap structures in high-use page families.

Scope:

Exclusions: Page-directory filtering, enhanced tables, and residual WET classes embedded in Markdown content.

Dependencies and blockers: Work Package 6; confirmed grid and card use criteria.

Risk: moderate

Definition of done:

Specific verification:

Components Exit Gate

All migrated shared UI and page-family fixtures must render in both languages without WET assets. Any shared component still required by the GCDS default layout must be assigned to a later work package explicitly.

Phase 4: Behavior

Work Package 8: Replace Page-Directory Overlays With Inline Structure

Proposed branch: feature/gcds-directory-structure

Purpose: Remove modal and side-panel dependencies from directory definitions and filters.

Scope:

Exclusions: Filtering JavaScript, sorting, pagination, and final content-file cleanup.

Dependencies and blockers: Work Package 7; no blockers because the approved #774 recommendation is inline structure.

Risk: serious

Definition of done:

Specific verification:

Work Package 9: Replace Directory Tag Filtering With Progressive Enhancement

Proposed branch: feature/gcds-directory-filtering

Purpose: Replace wb-tagfilter with a focused native form and vanilla JavaScript enhancement.

Scope:

Exclusions: Table sorting, pagination, and column visibility.

Dependencies and blockers: Work Package 8; product confirmation of the essential filter set.

Risk: serious

Definition of done:

Specific verification:

Work Package 10: Replace Enhanced Directory Table Behavior

Proposed branch: feature/gcds-directory-table

Purpose: Preserve a semantic directory table and add only justified enhancements.

Scope:

Exclusions: Enhancements without a documented user need and unrelated static tables.

Dependencies and blockers: Work Package 9; product decision on essential table tasks.

Risk: serious

Definition of done:

Specific verification:

Work Package 11: Replace Clauses Lightbox and WET Footnotes With Native References

Proposed branch: feature/gcds-native-references

Purpose: Replace two WET reference-navigation patterns with durable native links.

Scope:

Exclusions: Copy editing and restructuring unrelated procurement content.

Dependencies and blockers: Work Package 10; none beyond verification of unique identifiers.

Risk: moderate

Definition of done:

Specific verification:

Work Package 12: Remove or Replace Analytics Chart Enhancement

Proposed branch: feature/gcds-analytics

Purpose: Remove WET chart behavior while preserving authoritative analytics data.

Scope:

Exclusions: General analytics collection or reporting changes.

Dependencies and blockers: Work Package 11; evidence of user need and an approved library are blockers only if a chart is retained.

Risk: moderate

Definition of done:

Specific verification:

Behavior Exit Gate

All priority 1 requirements from issue #774 must be implemented or explicitly approved for removal. Essential content and tasks must have tested native baselines or documented exceptions.

Phase 5: Cleanup

Work Package 13: Migrate Language-Selection and Not-Found Pages

Proposed branch: feature/gcds-standalone-pages

Purpose: Migrate entry and error pages that bypass the shared Eleventy layout.

Scope:

Exclusions: Default layout activation and general content-page migration.

Dependencies and blockers: Work Package 12; decision on whether one splash image remains.

Risk: serious

Definition of done:

Specific verification:

Standalone Page Checkpoint

The splash and not-found pages must be independently ready for the final runtime removal because they do not inherit the shared shell.

Work Package 14: Migrate Remaining Inline Content Dependencies

Proposed branch: feature/gcds-content-cleanup

Purpose: Remove residual framework-dependent markup after reusable templates are stable.

Scope:

Exclusions: Unrelated content editing, translation correction, and new content.

Dependencies and blockers: Work Package 13; stable shared replacements for every recurring pattern.

Risk: serious

Definition of done:

Specific verification:

Work Package 15: Activate GCDS Default Layout and Remove Legacy Runtime

Proposed branch: feature/gcds-default-cutover

Purpose: Make GCDS authoritative in preview and remove runtime dependencies that are no longer needed.

Scope:

Exclusions: Merging PR #778 to main and production deployment changes.

Dependencies and blockers: Work Package 14; zero unexplained source and generated-output legacy dependencies.

Risk: critical

Definition of done:

Specific verification:

Cleanup Exit Gate

No unexplained legacy dependency may remain. Any approved exception must name its owner, affected routes, reason, and removal condition before full-site QA begins.

Phase 6: QA and Production Cutover

Work Package 16: Complete Full-Site QA and Production Cutover

Proposed branch: feature/gcds-release-readiness

Purpose: Verify the integrated migration and prepare the explicit production release decision.

Scope:

Exclusions: Automatic merging, changing production deployment infrastructure, and unrelated remediation.

Dependencies and blockers: Work Package 15; unresolved critical or serious findings block cutover.

Risk: critical

Definition of done:

Specific verification:

Final Exit Gate

The migration is complete only when PR #778 is explicitly approved and merged, production verification passes, and the project records any deferred exceptions with owners and follow-up issues. Issue #770 is not closed automatically by this plan.

Pattern Coverage

The following table demonstrates that each known migration area has an implementation owner.

Discovery Pattern Work Package
GCDS packages, CSS Shortcuts, parallel layout, head 1
Header, identity, language, search, global and site navigation, skip link 2
Footer and contextual links 3
Main shell, grid, title, breadcrumbs, date modified 4
Alerts, notices, archived state 5
On-this-page, Office navigation, downloads, contribution links, icons 6
Doormats, cards, collections, updates, roles, equal-height grids 7
Modal and side-panel overlays 8
Tag filtering and result announcements 9
Enhanced table behavior 10
Clauses lightbox and footnotes 11
Table-to-chart behavior 12
Splash randomizer and standalone shells 13
Inline content utilities, layout classes, and icons 14
Default layout, WET runtime, jQuery, FontAwesome, compatibility code 15
Full bilingual, accessibility, functional, and release verification 16

Issue Creation Workflow

This document is the review source for the proposed backlog. No child issue number in this plan is a GitHub issue number.

After approval:

  1. Commit this plan and supporting documentation to migration/gcds and push only to upstream.
  2. Move issue #776 to In Review.
  3. Present the final 16 proposed titles before creating GitHub issues.
  4. Create the issues with links to #770 and #776 and add them to Project 13 as Backlog.
  5. Record the assigned issue numbers in this plan in a separate documentation commit.
  6. Activate only Work Package 1; leave later work packages in Backlog until their dependencies pass.

Completion Assessment

Page details

Date modified: