You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

10 KiB

Complete Migration Checklist - MANDATORY STEPS

Overview

This checklist ensures NO migration steps are forgotten. Every component migration MUST complete ALL sections.

⚠️ CRITICAL: Enhanced Triple Migration Pattern

🔑 The Complete Pattern (ALL 4 REQUIRED)

  1. Database Migration: Replace legacy databaseUtil calls with PlatformServiceMixin methods
  2. SQL Abstraction: Replace raw SQL queries with service methods
  3. Notification Migration: Replace $notify() calls with helper methods + centralized constants
  4. Template Streamlining: Extract repeated expressions and complex logic to computed properties

INCOMPLETE: Any migration missing one of these steps COMPLETE: All four patterns implemented with code quality review

Pre-Migration Assessment

Date Time Context

  • Always use system date command to establish accurate time context
  • Use time log to track project progress
  • Use historical time durations to improve estimates

[ ] 1. Identify Legacy Patterns

  • Count databaseUtil imports and calls
  • Count raw SQL queries (SELECT, INSERT, UPDATE, DELETE)
  • Count $notify() calls
  • Count logConsoleAndDb() calls
  • Identify template complexity patterns (repeated expressions, long class strings)
  • Document total issues found

[ ] 2. Verify PlatformServiceMixin Setup

  • Component already imports PlatformServiceMixin
  • Component already has mixins: [PlatformServiceMixin]
  • If missing, add mixin first

Phase 1: Database Migration

[ ] 3. Replace Database Utility Calls

  • Remove import * as databaseUtil from "../db/databaseUtil"
  • Replace databaseUtil.retrieveSettingsForActiveAccount()this.$accountSettings()
  • Replace databaseUtil.mapQueryResultToValues()this.$mapQueryResultToValues()
  • Replace other databaseUtil.* calls with mixin equivalents

[ ] 4. Replace Logging Calls

  • Remove import { logConsoleAndDb } from "../db/index"
  • Replace logConsoleAndDb()this.$logAndConsole()

Phase 2: SQL Abstraction Migration

[ ] 5. Replace Raw Contact Operations

  • SELECT * FROM contacts WHERE did = ?this.$getContact(did)
  • DELETE FROM contacts WHERE did = ?this.$deleteContact(did)
  • UPDATE contacts SET x = ? WHERE did = ?this.$updateContact(did, changes)
  • INSERT INTO contactsthis.$insertContact(contact)

[ ] 6. Replace Other Raw SQL

  • SELECT * FROM settingsthis.$accountSettings()
  • UPDATE settingsthis.$saveSettings(changes)
  • Generic queries → appropriate service methods
  • NO RAW SQL ALLOWED: All database operations through service layer

Phase 3: Notification Migration

[ ] 7. Add Notification Infrastructure

  • Add import: import { createNotifyHelpers, TIMEOUTS } from "@/utils/notify"
  • Add property: notify!: ReturnType<typeof createNotifyHelpers>;
  • Add initialization: created() { this.notify = createNotifyHelpers(this.$notify); }

[ ] 8. Add Notification Constants to Central File

  • CRITICAL: Add constants to src/constants/notifications.ts (NOT local constants)
  • Use naming pattern: NOTIFY_[COMPONENT]_[ACTION] (e.g., NOTIFY_OFFER_SETTINGS_ERROR)
  • Import constants: import { NOTIFY_X, NOTIFY_Y } from "@/constants/notifications"
  • NO LOCAL CONSTANTS: All notification text must be centralized

[ ] 9. Replace Notification Calls

  • Warning: this.$notify({type: "warning"})this.notify.warning(CONSTANT.message, TIMEOUTS.LONG)
  • Error: this.$notify({type: "danger"})this.notify.error(CONSTANT.message, TIMEOUTS.LONG)
  • Success: this.$notify({type: "success"})this.notify.success(CONSTANT.message, TIMEOUTS.STANDARD)
  • Toast: this.$notify({type: "toast"})this.notify.toast(title, message, TIMEOUTS.SHORT)
  • Confirm: this.$notify({type: "confirm"})this.notify.confirm(message, onYes)
  • Standard patterns: Use this.notify.confirmationSubmitted(), this.notify.sent(), etc.

[ ] 10. Constants vs Literal Strings

  • Use constants for static, reusable messages
  • Use literal strings for dynamic messages with variables
  • Extract literals from complex modals - Even raw $notify calls should use constants for text
  • Document decision for each notification call

Phase 4: Template Streamlining

[ ] 11. Identify Template Complexity Patterns

  • Repeated CSS Classes: Long Tailwind strings used multiple times
  • Complex Configuration Objects: Multi-line objects in template
  • Repeated Function Calls: Same logic executed multiple times
  • Complex Conditional Logic: Nested ternary or complex boolean expressions

[ ] 12. Extract to Computed Properties

  • CSS Class Groups: Extract repeated styling to computed properties
  • Configuration Objects: Move router configs, form configs to computed
  • Conditional Logic: Extract complex v-if conditions to computed properties
  • Dynamic Values: Convert repeated calculations to cached computed properties

[ ] 13. Document Computed Properties

  • JSDoc Comments: Add comprehensive comments for all computed properties
  • Purpose Documentation: Explain what template complexity each property solves
  • Organized Sections: Group related computed properties with section headers
  • Descriptive Names: Use clear, descriptive names for computed properties

Phase 5: Code Quality Review

[ ] 14. Template Quality Assessment

  • Readability: Template is easy to scan and understand
  • Maintainability: Styling changes can be made in one place
  • Performance: Computed properties cache expensive operations
  • Consistency: Similar patterns use similar solutions

[ ] 15. Component Architecture Review

  • Single Responsibility: Component has clear, focused purpose
  • Props Interface: Clear, well-documented component props
  • Event Emissions: Appropriate event handling and emission
  • State Management: Component state is minimal and well-organized

[ ] 16. Code Organization Review

  • Import Organization: Imports are grouped logically (Vue, constants, services)
  • Method Organization: Methods are grouped by purpose with section headers
  • Property Organization: Data properties are documented and organized
  • Comment Quality: All complex logic has explanatory comments

Validation Phase

[ ] 17. Run Validation Script

  • Execute: scripts/validate-migration.sh
  • MUST show: "Technically Compliant" (not "Mixed Pattern")
  • Zero legacy patterns detected

[ ] 18. Run Linting

  • Execute: npm run lint-fix
  • Zero errors introduced
  • TypeScript compiles without errors

[ ] 19. Manual Code Review

  • NO databaseUtil imports or calls
  • NO raw SQL queries (SELECT, INSERT, UPDATE, DELETE)
  • NO $notify() calls with object syntax
  • NO logConsoleAndDb() calls
  • NO local notification constants
  • ALL database operations through service methods
  • ALL notifications through helper methods with centralized constants
  • ALL complex template logic extracted to computed properties

Documentation Phase

[ ] 20. Update Migration Documentation

  • Create docs/migration-testing/[COMPONENT]_MIGRATION.md
  • Document all changes made (database, SQL, notifications, template)
  • Include before/after examples for template streamlining
  • Note validation results
  • Provide a guide to finding the components in the user interface
  • Include code quality review notes

[ ] 21. Update Testing Tracker

  • Update docs/migration-testing/HUMAN_TESTING_TRACKER.md
  • Mark component as "Ready for Testing"
  • Include notes about migration completed with template streamlining

Human Testing Phase

[ ] 22. Test All Functionality

  • Core functionality works correctly
  • Database operations function properly
  • Notifications display correctly with proper timing
  • Error scenarios handled gracefully
  • Template rendering performs smoothly with computed properties
  • Cross-platform compatibility (web/mobile)

[ ] 23. Confirm Testing Complete

  • User confirms component works correctly
  • Update testing tracker with results
  • Mark as "Human Tested" in validation script

Final Validation

[ ] 24. Comprehensive Check

  • Component shows as "Technically Compliant" in validation
  • All manual testing passed
  • Zero legacy patterns remain
  • Template streamlining complete
  • Code quality review passed
  • Documentation complete
  • Ready for production

Wait for human confirmation before proceeding to next file unless directly overridden.

🚨 FAILURE CONDITIONS

INCOMPLETE MIGRATION if ANY of these remain:

  • databaseUtil imports or calls
  • Raw SQL queries (SELECT, INSERT, UPDATE, DELETE)
  • $notify() calls with object syntax
  • logConsoleAndDb() calls
  • Local notification constants (should be centralized)
  • Complex template expressions without computed properties
  • Missing notification helpers setup
  • Validation script shows "Mixed Pattern"

🎯 SUCCESS CRITERIA

COMPLETE MIGRATION requires ALL:

  • Zero legacy patterns detected
  • All database operations through service layer
  • All notifications through helper methods with centralized constants
  • Template complexity extracted to computed properties
  • Code quality review passed
  • Validation script shows "Technically Compliant"
  • Manual testing passed
  • Documentation complete

Templates and References

  • Migration Template: docs/migration-templates/component-migration.md
  • Notification Constants: src/constants/notifications.ts
  • PlatformServiceMixin: src/utils/PlatformServiceMixin.ts
  • Notification Helpers: src/utils/notify.ts
  • Validation Script: scripts/validate-migration.sh

⚠️ WARNING: This checklist exists because steps were previously forgotten. DO NOT skip any items. The enhanced triple migration pattern (Database + SQL + Notifications + Template Streamlining) is MANDATORY for all component migrations.

Author: Matthew Raymer
Date: 2024-07-07 Purpose: Prevent migration oversight by cementing ALL requirements including template quality Updated: Enhanced with template streamlining and code quality review phases