Release v4.15.0

.circleci/build-and-test/commands.yml

@@ -39,16 +39,45 @@
             sudo apt-get update
             sudo apt-get install -y libgbm-dev
             source /opt/circleci/.nvm/nvm.sh
-            nvm install v16.13
-            nvm alias default v16.13
+            nvm install v22.13.0
+            nvm alias default v22.13.0
             echo 'export NVM_DIR="/opt/circleci/.nvm"' >> $BASH_ENV
             echo "[ -s \"$NVM_DIR/nvm.sh\" ] && . \"$NVM_DIR/nvm.sh\"" >> $BASH_ENV
+            echo "nvm use v22.13.0" >> $BASH_ENV
+            nvm use v22.13.0
+            if command -v corepack >/dev/null 2>&1; then
+              corepack enable
+              corepack prepare yarn@4.6.0 --activate
+            else
+              npm install -g yarn@4.6.0
+            fi
+            node -v
+            yarn -v
 
-  disable-npm-audit:
+  install-yarn-packages:
+    description: Install frontend dependencies using Yarn.
+    parameters:
+      app-dir:
+        type: string
+        default: tdrs-frontend
     steps:
       - run:
-          name: Disable npm audit warnings in CI
-          command: npm set audit false
-
-  # This allows us to use the node orb to install packages within other commands
-  install-nodejs-packages: node/install-packages
+          name: Install Yarn packages
+          command: |
+            cd <<parameters.app-dir>>
+            if [ -z "$NVM_DIR" ]; then
+              export NVM_DIR="/opt/circleci/.nvm"
+            fi
+            if [ -s "$NVM_DIR/nvm.sh" ]; then
+              . "$NVM_DIR/nvm.sh"
+              nvm use v22.13.0
+            fi
+            if command -v corepack >/dev/null 2>&1; then
+              corepack enable
+              corepack prepare yarn@4.6.0 --activate
+            elif ! command -v yarn >/dev/null 2>&1; then
+              npm install -g yarn@4.6.0
+            fi
+            node -v
+            yarn -v
+            yarn install --immutable

.circleci/build-and-test/jobs.yml

@@ -25,18 +25,17 @@
     steps:
       - checkout
       - install-nodejs-machine
-      - disable-npm-audit
-      - install-nodejs-packages:
+      - install-yarn-packages:
           app-dir: tdrs-frontend
       - run:
           name: Run ESLint
-          command: cd tdrs-frontend; npm run lint
+          command: cd tdrs-frontend; yarn lint
       - run:
           name: Run Pa11y Accessibility Tests
-          command: cd tdrs-frontend; mkdir pa11y-screenshots/; export NODE_OPTIONS=--openssl-legacy-provider; npm run test:accessibility
+          command: cd tdrs-frontend; mkdir pa11y-screenshots/; export NODE_OPTIONS=--openssl-legacy-provider; yarn test:accessibility
       - run:
           name: Run Jest Unit Tests
-          command: cd tdrs-frontend; npm run test:ci
+          command: cd tdrs-frontend; yarn test:ci
       - upload-codecov:
           component: frontend
           coverage-report: ./tdrs-frontend/coverage/lcov.info
@@ -53,8 +52,7 @@
       - docker-compose-up-backend
       - docker-compose-up-frontend
       - install-nodejs-machine
-      - disable-npm-audit
-      - install-nodejs-packages:
+      - install-yarn-packages:
           app-dir: tdrs-frontend
       - run:
           name: Wait for backend to become available
@@ -82,7 +80,7 @@
             docker-compose exec web python manage.py loaddata cypress/users cypress/data_files cypress/regions cypress/profile_editing_regions cypress/profile_editing_users
       - run:
           name: Run Cypress e2e tests
-          command: cd tdrs-frontend; npm run test:e2e-ci
+          command: cd tdrs-frontend; yarn test:e2e-ci
       - store_artifacts:
           path: tdrs-frontend/cypress/screenshots/
       - store_artifacts:

.circleci/deployment/commands.yml

@@ -137,11 +137,12 @@
         type: string
     steps:
       - install-nodejs:
-          node-version: "16.13"
-      - disable-npm-audit
-      - install-nodejs-packages:
+          node-version: "22.13.0"
+      - run:
+          name: Log Node version
+          command: node -v
+      - install-yarn-packages:
           app-dir: tdrs-frontend
-          override-ci-command: npm ci --omit=dev --no-fund
       - get-app-deploy-strategy:
           appname: <<parameters.frontend-appname>>
       - run:

.circleci/deployment/jobs.yml

@@ -121,12 +121,11 @@
     steps:
       - checkout
       - install-nodejs-machine
-      - disable-npm-audit
-      - install-nodejs-packages:
+      - install-yarn-packages:
           app-dir: tdrs-frontend
       - run:
           name: Run Cypress e2e tests
-          command: cd tdrs-frontend; npm run test:e2e-ci -- --config baseUrl="https://tdp-frontend-develop.acf.hhs.gov" --env cypressToken=$CYPRESS_TOKEN,apiUrl="https://tdp-frontend-develop.acf.hhs.gov/v1",adminUrl="https://tdp-frontend-develop.acf.hhs.gov/admin"
+          command: cd tdrs-frontend; yarn test:e2e-ci --config baseUrl="https://tdp-frontend-develop.acf.hhs.gov" --env cypressToken=$CYPRESS_TOKEN,apiUrl="https://tdp-frontend-develop.acf.hhs.gov/v1",adminUrl="https://tdp-frontend-develop.acf.hhs.gov/admin"
       - store_artifacts:
           path: tdrs-frontend/cypress/screenshots/
       - store_artifacts:

.github/ISSUE_TEMPLATE/release-tracker-issue-template.md

@@ -0,0 +1,90 @@
+---
+name: Release Tracker
+about: Track the release handoff to OFA, staging validation, and production deployment.
+title: Release Tracker vX.X.X
+labels: ''
+assignees: ''
+
+---
+
+# Release Tracker Issue Template
+
+**TITLE:** Release vX.X.X
+
+**CONTENT:**
+
+### 🔗 Included Pull Requests (Dev Team)
+*List the PRs included in this release. **Testing instructions for each feature must be located within these linked PRs.***
+* #XXX - [Feature/Bugfix Title]
+* #XXX - [Feature/Bugfix Title]
+
+### ➡️ URL of GitHub Release Tag:
+https://github.com/raft-tech/TANF-app/releases/tag/vX.X.X
+
+---
+
+### 📦 1. Preparation & Handoff (Dev / UX / PM)
+*Ensuring the release branch is ready and documented before ACF takes over.*
+
+- [ ] **Release Tagged:** `develop` branch tagged with the new release version.
+- [ ] **Release Branch Created:** Branch cut from `develop`.
+- [ ] **PR Opened to Staging:** PR opened from the release branch to `HHS:main`.
+- [ ] **Testing Instructions Verified:** All linked PRs contain clear testing instructions for ACF validation.
+- [ ] **UX/Documentation Check:** UX team has reviewed the PRs, confirmed user-facing changes, and started drafting Release Notes and Knowledge Center guidance.
+- [ ] **Migration Flag:** Does this release include a database migration? **[Yes / No]** *(If Yes, rollback from production will be highly complex).*
+- [ ] **Handoff Complete:** Issue assigned to @[Alex_username] for Staging validation.
+
+---
+
+### 🧪 2. Staging Validation & QASP (ACF / Alex)
+*Tracking the status once ACF takes over deployment and testing.*
+
+- [ ] **Staging Cleared:** Team notified that Staging is about to be updated/restarted.
+- [ ] **Deployed to Staging:** PR merged and deployed to the Staging environment.
+- [ ] **Feature Validation:** Testing instructions from the linked PRs have been executed and passed.
+- [ ] **Regression Validation:** Core workflows (login, submissions, data integrity, etc.) remain functional.
+
+**🐛 Bug Tracking Protocol (If issues are found in Staging):**
+1. **Non-Dev Team:** Add a comment on this issue describing the bug/unexpected behavior.
+2. **Dev Team:** Review the comment, investigate root cause, and open a formal GitHub Issue.
+3. **Triage Decision:**
+    * *Revert:* If isolated to a new feature, revert the PR out of the release candidate.
+    * *Hotfix:* Warranted **only if** the bug blocks the release entirely AND the production release is needed ASAP. (Dev cuts hotfix PR against the release branch -> merged to `HHS:main` for re-testing).
+
+- [ ] **Documentation Finalized:** UX team confirms all Release Notes and Knowledge Center updates are finalized and ready for launch.
+
+---
+
+### 🚦 3. Production-Ready Sign-Off
+- [ ] ACF/Alex confirms all PRs are validated, no blocking bugs exist, documentation is finalized, and the release is approved for production deployment.
+
+---
+
+### 🛟 4. Rollback & Contingency Reference
+*Review before production deployment.*
+
+* **Pipeline/CircleCI Failure:** Retry the pipeline. If it fails again, requires a hotfix to unblock.
+* **Missing Config/Secrets (App crashes on boot):** Do not rollback. ACF updates environment variables in the production console and restarts the app.
+* **Third-Party API Blocked in Prod:** Dev provides an emergency hotfix to hide the broken UI component.
+* **Performance/Database Lockup Under Load:** Dev writes an emergency hotfix for the offending query.
+* **Critical Regression Post-Deploy:**
+    * *No migrations in release:* Rollback the deployment to the previous stable version.
+    * *Migrations in release:* Rollback is generally not possible; requires an emergency hotfix.
+
+---
+
+### 🚀 5. Production Deployment (ACF / Alex)
+*The final deployment executed by ACF.*
+
+- [ ] **Maintenance Mode:** Alex has enabled the maintenance page to ensure users are out of the system.
+- [ ] **Deployed to Prod:** PR opened and merged to `HHS:master`, triggering deployment.
+- [ ] **Post-Launch Verification:** Quick check that the production environment is stable post-deploy, and the maintenance page is deactivated.
+
+---
+
+### 📢 6. Post-Release Communication (PM / UX / ACF)
+*Closing the loop with users and stakeholders.*
+
+- [ ] **Release Notes Published:** (UX team) Plain-language, user-facing release notes and Knowledge Center guidance have been published.
+- [ ] **Stakeholders Notified:** (ACF) Any required external communication regarding the new version has been sent.
+- [ ] **Close this Issue:** (ACF / PM) The release is fully deployed and stable.

.gitignore

@@ -12,6 +12,7 @@ tdrs-frontend/yarn-error.log*
 tdrs-frontend/vars-frontend.yml
 tdrs-frontend/pa11y-screenshots/*
 tdrs-frontend/cypress/reports*
+tdrs-frontend/test-results*.xml
 .eslintcache
 downloads/
 
@@ -125,8 +126,3 @@ cypress.env.json
 tdrs-backend/*.pg
 tdrs-backend/django.log
 
-# Pytest cache
-tdrs-backend/.pytest_cache/*
-
-# frontend cypress test results
-tdrs-frontend/test-results*.xml

Taskfile.yml

@@ -227,21 +227,21 @@ tasks:
     dir: tdrs-frontend
     cmds:
       - docker compose -f docker-compose.local.yml up -d --build tdp-frontend
-      - docker compose -f docker-compose.local.yml exec tdp-frontend sh -c "npm install"
+      - docker compose -f docker-compose.local.yml exec tdp-frontend sh -c "corepack prepare yarn@4.6.0 && corepack yarn install"
       - docker compose -f docker-compose.local.yml down
 
   frontend-install:
     desc: Install frontend dependencies on host (uses local Node)
     dir: tdrs-frontend
     cmds:
-      - npm install
+      - corepack prepare yarn@4.6.0 --activate && yarn install
 
   frontend-update:
     desc: Rebuild frontend localdev image and install dependencies (no data wipe)
     dir: tdrs-frontend
     cmds:
       - docker compose -f docker-compose.local.yml up -d --build tdp-frontend
-      - docker compose -f docker-compose.local.yml exec tdp-frontend sh -c "npm install"
+      - docker compose -f docker-compose.local.yml exec tdp-frontend sh -c "corepack prepare yarn@4.6.0 && corepack yarn install"
 
   frontend-test-local:
     desc: Run frontend unit tests on host (watch-less)
@@ -268,7 +268,7 @@ tasks:
       JEST_ARGS: '{{.JEST_ARGS | default ""}}'
     cmds:
       - docker compose -f docker-compose.local.yml up -d --build tdp-frontend-test
-      - docker compose -f docker-compose.local.yml exec tdp-frontend-test sh -c "npm run test -- {{.JEST_ARGS}}"
+      - docker compose -f docker-compose.local.yml exec tdp-frontend-test sh -c "corepack prepare yarn@4.6.0 && corepack yarn install --mode=skip-build && CI=1 corepack yarn test --watchAll=false {{.JEST_ARGS}}"
 
   frontend-test-cov:
     desc: 'Run frontend unit tests with coverage in docker. E.g: task frontend-test-cov JEST_ARGS="--testPathPattern=FeedbackReports"'
@@ -277,14 +277,14 @@ tasks:
       JEST_ARGS: '{{.JEST_ARGS | default ""}}'
     cmds:
       - docker compose -f docker-compose.local.yml up -d --build tdp-frontend-test
-      - docker compose -f docker-compose.local.yml exec tdp-frontend-test sh -c "npm run test:cov -- {{.JEST_ARGS}}"
+      - docker compose -f docker-compose.local.yml exec tdp-frontend-test sh -c "corepack prepare yarn@4.6.0 && corepack yarn install --mode=skip-build && corepack yarn test:cov {{.JEST_ARGS}}"
 
   frontend-lint:
     desc: Run eslint in the frontend test container
     dir: tdrs-frontend
     cmds:
       - docker compose -f docker-compose.local.yml up -d --build tdp-frontend-test --quiet-pull
-      - docker compose -f docker-compose.local.yml exec -T tdp-frontend-test sh -c "npm run lint"
+      - docker compose -f docker-compose.local.yml exec -T tdp-frontend-test sh -c "corepack prepare yarn@4.6.0 && corepack yarn install --mode=skip-build && corepack yarn lint"
 
   # E2E / Cypress helpers
 
@@ -293,15 +293,44 @@ tasks:
     dir: tdrs-backend
     cmds:
       - export CYPRESS_TOKEN=local-cypress-token
-      - docker-compose exec web python manage.py delete_cypress_users -usernames new-cypress@teamraft.com cypress-admin@teamraft.com
-      - docker-compose exec web python manage.py loaddata cypress/users cypress/data_files cypress/regions cypress/profile_editing_regions cypress/profile_editing_users
+      - docker compose -f docker-compose.yml exec web python manage.py delete_cypress_users -usernames new-cypress@teamraft.com cypress-admin@teamraft.com cypress-data-analyst-dana@teamraft.com cypress-fra-data-analyst-derek@teamraft.com cypress-data-analyst-donna@teamraft.com cypress-fra-data-analyst-david@teamraft.com cypress-fra-ofa-regional-staff-rachel@acf.hhs.gov cypress-fra-ofa-regional-staff-robert@acf.hhs.gov cypress-fra-ofa-regional-staff-rita@acf.hhs.gov cypress-fra-ofa-regional-staff-ryan@acf.hhs.gov
+      - docker compose -f docker-compose.yml exec web python manage.py loaddata cypress/users cypress/data_files cypress/regions cypress/profile_editing_regions cypress/profile_editing_users
 
   frontend-e2e-local:
     desc: Run Cypress E2E tests locally (Cypress on host, app in docker)
     dir: tdrs-frontend
     cmds:
       - docker compose -f docker-compose.local.yml up -d --build tdp-frontend
-      - npm run test:e2e
+      - |
+        if command -v corepack >/dev/null 2>&1; then
+          corepack prepare yarn@4.6.0 --activate && env -u ELECTRON_RUN_AS_NODE yarn test:e2e
+        else
+          env -u ELECTRON_RUN_AS_NODE npx --yes @yarnpkg/cli-dist@4.6.0 test:e2e
+        fi
+
+  frontend-e2e-ci-local:
+    desc: Run Cypress E2E tests in command-line mode (headless, app in docker)
+    dir: tdrs-frontend
+    vars:
+      CYPRESS_TOKEN: '{{.CYPRESS_TOKEN | default "local-cypress-token"}}'
+    cmds:
+      - task: backend-up
+      - task: e2e-env-var-setup
+      - docker compose -f docker-compose.local.yml up -d --build tdp-frontend
+      - env -u ELECTRON_RUN_AS_NODE npx cypress verify || env -u ELECTRON_RUN_AS_NODE npx cypress install --force
+      - |
+        if command -v corepack >/dev/null 2>&1; then
+          env -u ELECTRON_RUN_AS_NODE yarn test:e2e-ci
+        else
+          env -u ELECTRON_RUN_AS_NODE npx --yes @yarnpkg/cli-dist@4.6.0 test:e2e-ci
+        fi
+
+  frontend-e2e-cmd:
+    desc: Run Cypress E2E tests headlessly from the command line (app in docker)
+    dir: tdrs-frontend
+    cmds:
+      - docker compose -f docker-compose.yml up -d --build tdp-frontend
+      - CYPRESS_TOKEN=${CYPRESS_TOKEN:-local-cypress-token} npm run test:e2e-ci
 
   k6:
     desc: Run k6 performance tests