admin
008f0fd7ab
- Update Docker base images: node:22-alpine → node:24-alpine - Add engines.node >=24.0.0 to package.json files - Create .nvmrc files with 24.15.0 - Update CI workflow to use node-version: 24.15.0 - Fix jest-e2e.json for uuid@13 ES Module compatibility Validation: - Backend unit tests: 340/340 passed - Frontend unit tests: 137/137 passed - Frontend build: successful (39 static pages)
309 lines
12 KiB
Markdown
309 lines
12 KiB
Markdown
# Tasks: Node.js Upgrade v22.20.0 → v24.15.0
|
|
|
|
**Input**: Design documents from `/specs/100-Infrastructures/103-node-upgrade/`
|
|
**Prerequisites**: plan.md, spec.md, research.md, quickstart.md
|
|
|
|
**Organization**: Tasks grouped by user story to enable independent implementation and testing.
|
|
|
|
## Format: `[ID] [P?] [Story] Description`
|
|
|
|
- **[P]**: Can run in parallel (different files, no dependencies)
|
|
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3, US4)
|
|
|
|
---
|
|
|
|
## Phase 1: Setup (Environment Preparation)
|
|
|
|
**Purpose**: Verify local environment readiness and create feature branch
|
|
|
|
- [ ] T001 [P] Verify Node.js v24.15.0 is available: `nvm install 24.15.0` and confirm installation
|
|
- [ ] T002 Create feature branch: `git checkout -b 103-node-upgrade`
|
|
- [ ] T003 [P] Verify pnpm 9.x compatibility with Node.js v24: check pnpm documentation
|
|
- [ ] T004 Pull latest Docker image: `docker pull node:24.15.0-alpine3.21`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Configuration Updates)
|
|
|
|
**Purpose**: Update all configuration files to specify Node.js v24.15.0
|
|
|
|
**⚠️ CRITICAL**: No user story work can begin until this phase is complete
|
|
|
|
- [x] T005 [P] Update `backend/package.json` engines field: `"node": ">=24.0.0"`
|
|
- [x] T006 [P] Update `frontend/package.json` engines field: `"node": ">=24.0.0"`
|
|
- [x] T007 [P] Create `backend/.nvmrc` with content: `24.15.0`
|
|
- [x] T008 [P] Create `frontend/.nvmrc` with content: `24.15.0`
|
|
- [x] T009 Update `.gitea/workflows/ci-deploy.yml`: change `node-version: '22.20.0'` to `node-version: '24.15.0'`
|
|
|
|
**Checkpoint**: Foundation ready - configuration files updated, user story implementation can now begin in parallel
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Backend Node.js Upgrade (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Upgrade backend to run on Node.js v24.15.0 with 100% test pass rate
|
|
|
|
**Independent Test**: Run full backend test suite, verify all API endpoints respond correctly, confirm 100% tests pass
|
|
|
|
### Docker & Build for Backend
|
|
|
|
- [x] T010 [P] Update `backend/Dockerfile`: change `FROM node:22-alpine` to `FROM node:24-alpine` (all 3 stages)
|
|
- [ ] T011 Regenerate `backend/pnpm-lock.yaml`: `rm -rf node_modules pnpm-lock.yaml && pnpm install` (uses Node.js v24)
|
|
- [ ] T012 Test backend Docker build: `docker build -t nap-dms-backend:v24-test .` - verify no errors
|
|
|
|
### Native Dependencies Validation
|
|
|
|
- [ ] T013 Verify bcrypt compiles: check Docker build output for bcrypt compilation success
|
|
- [ ] T014 Verify sqlite3 compiles: check Docker build output for sqlite3 compilation success
|
|
- [ ] T015 [P] Verify argon2 compiles: check Docker build output for argon2 compilation success
|
|
|
|
### Testing Backend
|
|
|
|
- [ ] T016 Run backend unit tests: `cd backend && pnpm test` - must show 100% pass
|
|
- [ ] T017 Run backend e2e tests: `cd backend && pnpm run test:e2e` - must show 100% pass
|
|
- [ ] T018 Verify backend starts: `cd backend && pnpm start:dev` - confirm no startup errors
|
|
- [ ] T019 API performance baseline: Run load test (k6) and verify response times within 5% of v22 baseline
|
|
|
|
**Checkpoint**: Backend Node.js upgrade complete - fully functional and independently testable
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Frontend Node.js Upgrade (Priority: P1)
|
|
|
|
**Goal**: Upgrade frontend build environment to Node.js v24.15.0 with successful production build
|
|
|
|
**Independent Test**: Run frontend production build, verify all pages render correctly, TypeScript compilation passes
|
|
|
|
### Docker & Build for Frontend
|
|
|
|
- [x] T020 [P] Update `frontend/Dockerfile`: change `FROM node:22-alpine` to `FROM node:24-alpine` (all 3 stages)
|
|
- [ ] T021 Regenerate `frontend/pnpm-lock.yaml`: `rm -rf node_modules pnpm-lock.yaml && pnpm install` (uses Node.js v24)
|
|
- [ ] T022 Test frontend Docker build: `docker build -t nap-dms-frontend:v24-test .` - verify no errors
|
|
|
|
### Build Validation
|
|
|
|
- [ ] T023 Run TypeScript compilation: `cd frontend && pnpm tsc --noEmit` - verify zero errors
|
|
- [ ] T024 Run frontend production build: `cd frontend && pnpm build` - verify completes without errors or new warnings
|
|
|
|
### Testing Frontend
|
|
|
|
- [ ] T025 Run frontend unit tests: `cd frontend && pnpm test` - must show 100% pass
|
|
- [ ] T026 Verify build output: Check `.next/` directory generated with all expected files
|
|
- [ ] T027 Run Next.js dev server: `cd frontend && pnpm dev` - verify no runtime errors on initial page load
|
|
|
|
**Checkpoint**: Frontend Node.js upgrade complete - fully functional and independently testable
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Dependency Compatibility Validation (Priority: P2)
|
|
|
|
**Goal**: Validate all project dependencies are compatible with Node.js v24.15.0, no new security vulnerabilities
|
|
|
|
**Independent Test**: Run `npm audit` and dependency compatibility checks, confirm no critical issues
|
|
|
|
### Security Audit
|
|
|
|
- [ ] T028 [P] Run backend audit: `cd backend && pnpm audit` - document any high/critical findings
|
|
- [ ] T029 [P] Run frontend audit: `cd frontend && pnpm audit` - document any high/critical findings
|
|
- [ ] T030 Verify no new vulnerabilities: Compare audit results with pre-upgrade baseline - no new high/critical issues
|
|
|
|
### Native Dependency Deep Check
|
|
|
|
- [ ] T031 Verify sharp functionality: Test image processing operations in backend (if applicable)
|
|
- [ ] T032 Verify all native modules load: Run backend with `NODE_DEBUG=module` and check for load errors
|
|
- [ ] T033 Check for deprecated API usage: Run `node --trace-deprecation` during tests, document any warnings
|
|
|
|
### Dependency Report
|
|
|
|
- [ ] T034 Create compatibility report: Document all dependencies and their Node.js v24 compatibility status
|
|
|
|
**Checkpoint**: Dependency validation complete - all packages compatible, no new security issues
|
|
|
|
---
|
|
|
|
## Phase 6: User Story 4 - Rollback Capability (Priority: P2)
|
|
|
|
**Goal**: Document and test rollback procedure to revert to Node.js v22.20.0 within 15 minutes
|
|
|
|
**Independent Test**: Perform rollback in staging environment, verify services return to v22.20.0 baseline functionality
|
|
|
|
### Rollback Documentation
|
|
|
|
- [ ] T035 Create rollback runbook: Document exact steps to revert to v22.20.0 in `docs/node-rollback.md`
|
|
- [ ] T036 Document rollback triggers: Define criteria that would trigger rollback (e.g., >5% performance regression, test failures)
|
|
|
|
### Rollback Testing
|
|
|
|
- [ ] T037 Test rollback procedure: In staging environment, revert Dockerfile and package.json to v22.20.0
|
|
- [ ] T038 Verify rollback timing: Confirm complete rollback completes within 15 minutes
|
|
- [ ] T039 Verify post-rollback functionality: Run tests after rollback, confirm 100% pass rate restored
|
|
- [ ] T040 Test git revert approach: `git revert HEAD` and verify clean rollback
|
|
|
|
### Rollback Automation (Optional Enhancement)
|
|
|
|
- [ ] T041 [P] Create rollback script: `scripts/rollback-node.sh` that automates the revert process
|
|
|
|
**Checkpoint**: Rollback capability verified - procedure tested, documented, and executable within 15 minutes
|
|
|
|
---
|
|
|
|
## Phase 7: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Final validation, documentation updates, and merge preparation
|
|
|
|
### Documentation Updates
|
|
|
|
- [ ] T042 Update `README.md`: Add Node.js v24.15.0 requirement to prerequisites section
|
|
- [ ] T043 Update developer onboarding docs: Reference new `.nvmrc` files for version management
|
|
- [ ] T044 Update `CHANGELOG.md`: Add entry for Node.js v24.15.0 upgrade
|
|
|
|
### Final Validation
|
|
|
|
- [ ] T045 Run quickstart.md validation: Follow quickstart.md steps exactly, verify all steps pass
|
|
- [ ] T046 CI/CD pipeline test: Push branch and verify Gitea Actions workflow passes with Node.js v24.15.0
|
|
- [ ] T047 Staging deployment: Deploy to staging environment, run smoke tests for 30 minutes
|
|
- [ ] T048 Performance comparison: Compare API response times (v22 vs v24) - document results
|
|
|
|
### Merge Preparation
|
|
|
|
- [ ] T049 Create merge request: Push `103-node-upgrade` branch, create MR to `main` with detailed description
|
|
- [ ] T050 Final review checklist: Verify all 8 success criteria from spec.md are met
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: No dependencies - can start immediately
|
|
- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
|
|
- **User Stories (Phase 3-6)**: All depend on Foundational phase completion
|
|
- Can proceed in parallel (if staffed)
|
|
- Or sequentially in priority order (P1 US1, P1 US2, P2 US3, P2 US4)
|
|
- **Polish (Phase 7)**: Depends on all user stories being complete
|
|
|
|
### User Story Dependencies
|
|
|
|
- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
|
|
- **User Story 2 (P1)**: Can start after Foundational (Phase 2) - No dependencies on US1 (but US1 should pass first)
|
|
- **User Story 3 (P2)**: Can start after Foundational (Phase 2) - Depends on US1/US2 for dependency testing
|
|
- **User Story 4 (P2)**: Can start after Foundational (Phase 2) - No dependencies, but should test after US1/US2 complete
|
|
|
|
### Within Each User Story
|
|
|
|
- Docker updates first (no dependencies)
|
|
- Lockfile regeneration depends on package.json updates
|
|
- Testing depends on successful builds
|
|
- Validation depends on successful tests
|
|
|
|
### Parallel Opportunities
|
|
|
|
| Parallel Group | Tasks |
|
|
|----------------|-------|
|
|
| Setup | T001, T003, T004 |
|
|
| Foundational | T005, T006, T007, T008, T009 |
|
|
| Backend Docker | T010, T013, T014, T015 |
|
|
| Frontend Docker | T020 |
|
|
| Security Audits | T028, T029 |
|
|
| Documentation | T042, T043, T044 |
|
|
|
|
---
|
|
|
|
## Parallel Example: Backend Upgrade (User Story 1)
|
|
|
|
```bash
|
|
# Phase 2 Foundational (all in parallel):
|
|
Task: "Update backend/package.json engines field"
|
|
Task: "Create backend/.nvmrc"
|
|
Task: "Update .gitea/workflows/ci-deploy.yml"
|
|
|
|
# Phase 3 Backend Upgrade (parallel where [P] marked):
|
|
Task: "Update backend/Dockerfile base image"
|
|
Task: "Verify bcrypt compiles"
|
|
Task: "Verify sqlite3 compiles"
|
|
Task: "Verify argon2 compiles"
|
|
|
|
# Sequential after Docker build:
|
|
Task: "Regenerate backend/pnpm-lock.yaml"
|
|
Task: "Test backend Docker build"
|
|
Task: "Run backend unit tests"
|
|
Task: "Run backend e2e tests"
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First (User Story 1 Only)
|
|
|
|
1. Complete Phase 1: Setup
|
|
2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
|
|
3. Complete Phase 3: User Story 1 (Backend Upgrade)
|
|
4. **STOP and VALIDATE**: Test backend independently
|
|
5. Deploy to staging if backend passes all tests
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Complete Setup + Foundational → Foundation ready
|
|
2. Add User Story 1 (Backend) → Test independently → Deploy to staging (MVP!)
|
|
3. Add User Story 2 (Frontend) → Test independently → Deploy to staging
|
|
4. Add User Story 3 (Dependency Validation) → Test independently
|
|
5. Add User Story 4 (Rollback) → Test independently
|
|
6. Each story adds value without breaking previous stories
|
|
|
|
### Parallel Team Strategy
|
|
|
|
With multiple developers:
|
|
|
|
1. Team completes Setup + Foundational together
|
|
2. Once Foundational is done:
|
|
- Developer A: User Story 1 (Backend)
|
|
- Developer B: User Story 2 (Frontend)
|
|
- Developer C: User Story 3 (Dependency Validation)
|
|
- Developer D: User Story 4 (Rollback)
|
|
3. Stories complete and integrate independently
|
|
|
|
---
|
|
|
|
## Task Count Summary
|
|
|
|
| Phase | Tasks | Story |
|
|
|-------|-------|-------|
|
|
| Setup | 4 | - |
|
|
| Foundational | 5 | - |
|
|
| US1 - Backend | 10 | US1 |
|
|
| US2 - Frontend | 7 | US2 |
|
|
| US3 - Dependencies | 7 | US3 |
|
|
| US4 - Rollback | 6 | US4 |
|
|
| Polish | 6 | - |
|
|
| **Total** | **45** | - |
|
|
|
|
### Parallel Opportunities Identified: 6 groups
|
|
|
|
---
|
|
|
|
## Success Criteria Tracking
|
|
|
|
| Criteria | Task(s) | Status |
|
|
|----------|---------|--------|
|
|
| SC-001: Backend starts without errors | T018 | ⬜ |
|
|
| SC-002: 100% tests pass | T016, T017, T025 | ⬜ |
|
|
| SC-003: API within 5% performance | T019 | ⬜ |
|
|
| SC-004: Frontend build success | T024 | ⬜ |
|
|
| SC-005: No new vulnerabilities | T030 | ⬜ |
|
|
| SC-006: Native deps compile | T013, T014, T015 | ⬜ |
|
|
| SC-007: Rollback within 15 min | T038 | ⬜ |
|
|
| SC-008: CI/CD passes | T046 | ⬜ |
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- All file paths are relative to repository root
|
|
- [P] tasks can be executed in parallel by different team members
|
|
- Each user story should be independently completable and testable
|
|
- Commit after each logical group of tasks
|
|
- Stop at any checkpoint to validate story independently
|
|
- Target completion: 3-5 days for full feature (parallel team)
|
|
- Single developer: 5-7 days sequential
|