@jmruthers/pace-core 0.5.193 → 0.6.2

package/docs/migration/DOCUMENTATION_STRUCTURE.md

@@ -0,0 +1,441 @@
+# Documentation Structure Guidelines
+
+**Purpose:** Define clear structure and responsibilities for CHANGELOG.md and migration documentation to prevent overlap and maintain single source of truth.
+
+## Documentation Hierarchy
+
+```
+CHANGELOG.md (High-level announcements, links to detailed guides)
+├── docs/migration/README.md (Index/navigation)
+├── docs/migration/MIGRATION_GUIDE.md (General migration patterns)
+├── docs/migration/V0.X_TO_V0.Y_MIGRATION.md (Version-specific migrations)
+├── docs/migration/V0.6.0_REACT_19_MIGRATION.md (Feature-specific migrations)
+├── docs/migration/database-changes-december-2025.md (Database-specific)
+└── docs/migration/V0.5.190_person-scoped-profiles-migration-guide.md (Feature-specific)
+```
+
+## CHANGELOG.md Responsibilities
+
+### ✅ What CHANGELOG.md SHOULD Include
+
+1. **High-Level Announcements**
+   - Breaking changes summary
+   - New features summary
+   - Deprecations summary
+   - Bug fixes summary
+
+2. **Brief Summaries**
+   - One-line descriptions of changes
+   - Key impact statements
+   - Version numbers and dates
+
+3. **Links to Detailed Guides**
+   - Links to migration guides for breaking changes
+   - Links to feature documentation
+   - Links to troubleshooting guides
+
+4. **Quick Migration Notes**
+   - Brief "what changed" statements
+   - Links to detailed migration guides
+   - Critical warnings (e.g., "⚠️ CRITICAL: Database migrations required")
+
+### ❌ What CHANGELOG.md SHOULD NOT Include
+
+1. **Detailed Migration Steps**
+   - Step-by-step instructions
+   - Code examples (unless very brief)
+   - Configuration file examples
+   - Troubleshooting details
+
+2. **Duplicate Content**
+   - Content that exists in migration guides
+   - Detailed explanations already in docs
+   - Long code blocks
+
+3. **Version-Specific Details**
+   - Detailed version upgrade paths
+   - Specific migration commands
+   - Database migration file names (unless critical)
+
+## Migration Documentation Responsibilities
+
+### ✅ What Migration Docs SHOULD Include
+
+1. **Step-by-Step Instructions**
+   - Detailed migration steps
+   - Code examples (before/after)
+   - Configuration changes
+   - Command-line instructions
+
+2. **Code Examples**
+   - Before/after code comparisons
+   - Complete working examples
+   - Common patterns and anti-patterns
+
+3. **Troubleshooting**
+   - Common issues and solutions
+   - Error messages and fixes
+   - Edge cases
+
+4. **Complete Context**
+   - Why changes were made
+   - Impact analysis
+   - Migration timeline
+   - Testing checklists
+
+### ❌ What Migration Docs SHOULD NOT Include
+
+1. **High-Level Summaries**
+   - Brief announcements (that's CHANGELOG's job)
+   - Marketing-style descriptions
+   - Non-actionable information
+
+2. **Duplicate Content**
+   - Content duplicated from other migration guides
+   - Content that should be in CHANGELOG
+
+## Content Strategy by Type
+
+### Breaking Changes
+
+**CHANGELOG.md:**
+```markdown
+## [0.6.0] - 2025-01-28
+
+### Changed
+- **BREAKING**: Upgraded from React 18.3.1 to React 19.2.3
+- **BREAKING**: Database schema changes (table naming standardization)
+
+### Migration Notes
+- **React 19 Upgrade**: See [React 19 Migration Guide](./docs/migration/V0.6.0_REACT_19_MIGRATION.md)
+- **Database Changes**: See [v0.5.190 → v0.6.1 Migration Guide](./docs/migration/V0.5.190_TO_V0.6.1_MIGRATION.md)
+```
+
+**Migration Doc:**
+```markdown
+# React 19 Migration Guide
+
+## Step 1: Update Dependencies
+
+```bash
+npm install react@^19.2.3 react-dom@^19.2.3
+```
+
+## Step 2: Update Vite Configuration
+
+```typescript
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
+  ],
+})
+```
+
+[... detailed steps ...]
+```
+
+### New Features
+
+**CHANGELOG.md:**
+```markdown
+### Added
+- **useFormDialog Hook**: Generic React hook for managing form dialog state
+- **DateTimeField Component**: Form input component for datetime values with automatic UTC ↔ timezone conversion
+```
+
+**Migration Doc (if needed):**
+```markdown
+# Using New Features
+
+## useFormDialog Hook
+
+```tsx
+import { useFormDialog } from '@jmruthers/pace-core';
+
+const formDialog = useFormDialog<FormData>({
+  defaultValues: { name: '', email: '' }
+});
+```
+
+[... usage examples ...]
+```
+
+### Minor Version Changes
+
+**CHANGELOG.md:**
+```markdown
+## [0.5.109] - 2025-11-03
+
+### Changed
+- **Session Tracking Hook API**: Removed `trackLogin()` and `trackLogout()` methods
+
+### Migration Guide
+
+### Upgrading from 0.5.108 to 0.5.109
+
+**Breaking Change**: The `useSessionTracking` hook no longer provides `trackLogin()` and `trackLogout()` methods.
+
+**Migration Steps:**
+1. Remove manual tracking calls
+2. Keep event switch tracking
+3. Apply database migrations
+
+[... brief migration guide ...]
+```
+
+**Note:** For minor versions, it's acceptable to include brief migration guides directly in CHANGELOG if they're simple. For complex migrations, create a dedicated migration guide.
+
+## File Naming Conventions
+
+### Migration Guides
+
+All migration guides should include version or date stamps in their filenames for clarity:
+
+- **Version-specific**: `V0.X_TO_V0.Y_MIGRATION.md`
+  - Example: `V0.5.190_TO_V0.6.1_MIGRATION.md`
+  - ✅ Already includes version numbers
+
+- **Feature-specific**: `V{VERSION}_{FEATURE}-migration.md` or `V{VERSION}_{FEATURE}-migration-guide.md`
+  - Example: `V0.6.0_REACT_19_MIGRATION.md` (introduced in v0.6.0)
+  - Example: `V0.5.190_person-scoped-profiles-migration-guide.md` (introduced in v0.5.190)
+  - **Rationale**: Version at start ensures chronological sorting and makes it clear which version introduced the feature
+
+- **Database-specific**: `database-changes-{DATE}.md` or `database-changes-{DATE}-V{VERSION}.md`
+  - Example: `database-changes-december-2025.md` (date-based, already in use)
+  - Example: `database-changes-december-2025-V0.5.190.md` (if version context needed)
+  - **Rationale**: Dates are clear for database changes, but version can help if needed
+
+- **General/Topic-specific**: `V{VERSION}_{TOPIC}-migration.md` or `{DATE}_{TOPIC}-migration.md`
+  - Example: `V0.4.0_rbac-migration.md` (if version-specific)
+  - Example: `V0.3.44_organisation-context-timing-fix.md` (if version-specific)
+  - **Rationale**: Version at start ensures chronological sorting. Use version if tied to specific release, date if it's a fix/change
+
+### Naming Rules
+
+1. **Always include version or date** - Makes it clear when/what the migration relates to
+2. **Version at the start** - Put version number at the beginning of filename for chronological sorting
+3. **Use version for feature migrations** - Tied to specific release
+4. **Use date for database changes** - Clear chronological reference
+5. **Use version for fixes** - Tied to specific release
+6. **Be consistent** - Follow the pattern once established
+
+### Documentation Files (No Version Needed)
+
+These are general documentation files that don't need version stamps:
+
+- **Index**: `README.md`
+- **General Guide**: `MIGRATION_GUIDE.md` (includes quick reference table)
+- **Structure Guidelines**: `DOCUMENTATION_STRUCTURE.md`
+
+### Migration Guides (Version Required)
+
+**All migration guides must include version or date stamps:**
+
+- ✅ `V0.6.0_REACT_19_MIGRATION.md` - Feature migration with version at start
+- ✅ `V0.5.190_person-scoped-profiles-migration-guide.md` - Feature migration with version at start
+- ✅ `V0.3.44_organisation-context-timing-fix.md` - Fix migration with version at start
+- ✅ `V0.5.190_TO_V0.6.1_MIGRATION.md` - Version-specific migration
+- ✅ `database-changes-december-2025.md` - Database changes with date
+- ✅ `V0.4.0_rbac-migration.md` - RBAC migration (introduced in v0.4.0)
+- ✅ Service architecture documentation is in `/docs/architecture/services.md` (not a migration guide)
+
+## Link Strategy
+
+### From CHANGELOG to Migration Docs
+
+Always use relative paths:
+```markdown
+- See [React 19 Migration Guide](./docs/migration/REACT_19_MIGRATION_V0.6.0.md)
+```
+
+### Between Migration Docs
+
+Use relative paths:
+```markdown
+- See [Database Changes December 2025](./database-changes-december-2025.md)
+- See [React 19 Migration Guide](./V0.6.0_REACT_19_MIGRATION.md)
+```
+
+### From Migration Docs to CHANGELOG
+
+Use relative paths:
+```markdown
+- See [CHANGELOG.md](../../CHANGELOG.md) for version history
+```
+
+## Version-Specific Migration Guides
+
+### When to Create a Version-Specific Guide
+
+Create a dedicated migration guide when:
+- ✅ Major version upgrade (e.g., 0.5.x → 0.6.x)
+- ✅ Multiple breaking changes in one version
+- ✅ Complex migration requiring multiple steps
+- ✅ Database migrations required
+- ✅ Significant API changes
+
+### When to Keep in CHANGELOG
+
+Keep migration guide in CHANGELOG when:
+- ✅ Minor version upgrade with simple changes
+- ✅ Single breaking change that's straightforward
+- ✅ No database migrations required
+- ✅ Simple code updates only
+
+## Review Checklist
+
+Before adding content to CHANGELOG or migration docs:
+
+### CHANGELOG Review
+
+- [ ] Is this a high-level announcement?
+- [ ] Is this a brief summary (not detailed steps)?
+- [ ] Are detailed migration steps linked to migration docs?
+- [ ] Is there duplicate content in migration docs?
+- [ ] Are all links working and pointing to correct files?
+
+### Migration Doc Review
+
+- [ ] Are step-by-step instructions included?
+- [ ] Are code examples provided?
+- [ ] Is troubleshooting information included?
+- [ ] Are links to related docs included?
+- [ ] Is there duplicate content from CHANGELOG?
+- [ ] Is there duplicate content from other migration docs?
+
+## Maintenance Guidelines
+
+### Regular Reviews
+
+1. **After Each Release**
+   - Review CHANGELOG for duplicate content
+   - Verify all links work
+   - Check migration docs are referenced correctly
+
+2. **Quarterly**
+   - Review all migration docs for outdated content
+   - Consolidate overlapping guides
+   - Update links and references
+
+3. **Before Major Releases**
+   - Plan migration guide structure
+   - Identify potential overlaps
+   - Create clear documentation hierarchy
+
+### Content Updates
+
+1. **When Adding Breaking Changes**
+   - Add brief summary to CHANGELOG
+   - Create or update migration guide
+   - Link from CHANGELOG to migration guide
+
+2. **When Adding New Features**
+   - Add feature announcement to CHANGELOG
+   - Add usage examples to migration guide (if migration needed)
+   - Link from CHANGELOG if detailed guide exists
+
+3. **When Fixing Bugs**
+   - Add fix to CHANGELOG
+   - Add troubleshooting to migration guide (if relevant)
+   - Link if detailed troubleshooting needed
+
+## Examples
+
+### ✅ Good CHANGELOG Entry
+
+```markdown
+## [0.6.0] - 2025-01-28
+
+### Changed
+- **BREAKING**: Upgraded from React 18.3.1 to React 19.2.3
+- **BREAKING**: Database schema changes (table naming standardization)
+
+### Migration Notes
+
+**⚠️ CRITICAL**: This version includes major breaking changes.
+
+- **React 19 Upgrade**: See [React 19 Migration Guide](./docs/migration/V0.6.0_REACT_19_MIGRATION.md)
+- **Complete Migration**: See [v0.5.190 → v0.6.1 Migration Guide](./docs/migration/V0.5.190_TO_V0.6.1_MIGRATION.md)
+```
+
+### ❌ Bad CHANGELOG Entry
+
+```markdown
+## [0.6.0] - 2025-01-28
+
+### Changed
+- **BREAKING**: Upgraded from React 18.3.1 to React 19.2.3
+
+### Migration Steps
+
+**Step 1: Update Dependencies**
+
+```bash
+npm install react@^19.2.3 react-dom@^19.2.3
+npm install -D @types/react@^19.2.7 @types/react-dom@^19.2.3
+```
+
+**Step 2: Update Vite Configuration**
+
+```typescript
+export default defineConfig({
+  plugins: [
+    react({
+      babel: {
+        plugins: ['babel-plugin-react-compiler'],
+      },
+    }),
+  ],
+})
+```
+
+[... many more steps ...]
+```
+
+### ✅ Good Migration Guide Entry
+
+```markdown
+# React 19 Migration Guide
+
+## Step 1: Update Dependencies
+
+```bash
+npm install react@^19.2.3 react-dom@^19.2.3
+npm install -D @types/react@^19.2.7 @types/react-dom@^19.2.3
+npm install -D @vitejs/plugin-react@^5.1.2
+npm install -D babel-plugin-react-compiler@latest
+```
+
+## Step 2: Update Vite Configuration
+
+[... detailed instructions ...]
+
+## Troubleshooting
+
+### Issue: TypeScript errors with child.props
+
+[... detailed troubleshooting ...]
+```
+
+### ❌ Bad Migration Guide Entry
+
+```markdown
+# React 19 Migration Guide
+
+React 19 has been released! This is a major upgrade that includes...
+
+[... marketing content, no actionable steps ...]
+```
+
+## Summary
+
+- **CHANGELOG.md**: Announce, summarize, link
+- **Migration Docs**: Instruct, demonstrate, troubleshoot
+- **No Duplication**: Each piece of information lives in one place
+- **Clear Links**: Easy navigation between related content
+- **Regular Review**: Keep structure clean and maintainable
+

package/docs/migration/MIGRATION_GUIDE.md

@@ -160,31 +160,9 @@ This breaking change was made for security reasons:
 - Provides consistent user experience across all apps
 - Improves overall security posture
 
-### v2.0.0 - Service Architecture Changes
+### Service Architecture
 
-**Status**: ⚠️ **BREAKING CHANGE**  
-**Date**: December 2024  
-**Impact**: Medium - Affects apps using service architecture
-
-#### What Changed
-
-The library now uses a service-based architecture with pure TypeScript service classes and React integration through providers and hooks.
-
-#### Key Changes
-
-- ✅ **New Service Layer**: Pure TypeScript classes for business logic
-- ✅ **Provider Layer**: React context integration for services
-- ✅ **Hook Layer**: Reactive hooks for component integration
-- ✅ **Backward Compatible**: `UnifiedAuthProvider` maintained for compatibility
-
-#### Migration
-
-The service architecture is now the default. Existing code continues to work without changes:
-
-```tsx
-// Works out of the box - uses service architecture internally
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-```
+**Note**: Service architecture documentation is available in [Architecture Documentation](../architecture/services.md). The service-based architecture is backward compatible - existing code using `UnifiedAuthProvider` continues to work without changes as it uses the service architecture internally.
 
 ## Version-Specific Migrations
 
@@ -933,8 +911,8 @@ export default defineConfig({
     
     // New dependencies
     "@jmruthers/pace-core": "^2.0.0",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "@supabase/supabase-js": "^2.38.0",
     "zod": "^3.22.0"
   },
@@ -944,8 +922,8 @@ export default defineConfig({
     "@types/react-dom": "^17.0.0",
     
     // New dev dependencies
-    "@types/react": "^18.2.0",
-    "@types/react-dom": "^18.2.0",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^4.0.0",
     "vite": "^4.4.0",
     "typescript": "^5.0.0"

package/docs/migration/README.md

@@ -6,12 +6,25 @@ reviewedBy: documentation-standards-audit
 
 # Migration Guide
 
-> **🔄 Upgrade and Migration** | [Unified Migration Guide](./MIGRATION_GUIDE.md) | [RBAC Migration](./rbac-migration.md)
+> **🔄 Upgrade and Migration** | [Unified Migration Guide](./MIGRATION_GUIDE.md) | [RBAC Migration](./V0.4.0_rbac-migration.md)
 
 [← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents) | [Next: Unified Migration Guide →](./MIGRATION_GUIDE.md)
 
 Complete migration guides for upgrading to and between versions of `@jmruthers/pace-core`.
 
+## 📖 Documentation Structure
+
+This migration documentation follows a clear structure to help you find the information you need:
+
+- **CHANGELOG.md**: High-level announcements and summaries with links to detailed guides
+- **Migration Guides**: Step-by-step instructions, code examples, and troubleshooting
+  - **Version-Specific**: `V0.5.190_TO_V0.6.1_MIGRATION.md` - Complete migration for specific versions
+  - **Feature-Specific**: `V0.6.0_REACT_19_MIGRATION.md`, `V0.4.0_rbac-migration.md` - Focused guides for specific features (with version stamps at start)
+  - **Database-Specific**: `database-changes-december-2025.md` - Database schema changes
+  - **General**: `MIGRATION_GUIDE.md` - General migration patterns and best practices
+
+**For documentation structure guidelines, see:** [Documentation Structure](./DOCUMENTATION_STRUCTURE.md)
+
 ## 📚 Start Here: Unified Migration Guide
 
 **For all migrations, start with:** [Complete Migration Guide](./MIGRATION_GUIDE.md)
@@ -29,6 +42,8 @@ The unified guide provides:
 - [Quick Migration Checklist](#-quick-migration-checklist)
 - [Version Migrations](#-version-migrations)
 - [Critical Fixes](#-critical-fixes)
+  - [v0.5.190 → v0.6.1 Comprehensive Migration Guide](#v05190--v061-comprehensive-migration-guide)
+  - [Person-Scoped Profiles Migration](#person-scoped-profiles-migration-v05190)
 - [From Other Libraries](#-from-other-libraries)
 - [RBAC Migration](#-rbac-migration)
 - [Migration Tools](#-migration-tools)
@@ -64,6 +79,25 @@ This guide covers:
 
 ## 🚨 Critical Fixes
 
+### v0.5.190 → v0.6.1 Comprehensive Migration Guide
+
+**NEW**: Complete migration guide for upgrading from v0.5.190 to v0.6.1.
+
+**Breaking Changes:**
+- React 19 upgrade (all apps must upgrade)
+- Database schema changes (table naming standardization)
+- Person-scoped profiles migration
+
+**Migration Guide**: [v0.5.190 → v0.6.1 Migration Guide](./V0.5.190_TO_V0.6.1_MIGRATION.md)
+
+**Quick Summary**:
+- Upgrade React to 19.2.3+
+- Apply database migrations
+- Update all table name references
+- Remove `organisation_id` filters from profile queries
+- Configure React Compiler
+- See full guide for detailed instructions
+
 ### Person-Scoped Profiles Migration (v0.5.190+)
 
 **BREAKING CHANGE**: Profiles (membership, medical, and contact) have been migrated from organisation-scoped to person-scoped.
@@ -74,7 +108,7 @@ This guide covers:
 - One membership per person (enforced by unique constraint)
 - Related tables (`pace_consent`, `pace_identification`, `pace_qualification`, etc.) also no longer have `organisation_id`
 
-**Migration Guide**: [Person-Scoped Profiles Migration Guide](./person-scoped-profiles-migration-guide.md)
+**Migration Guide**: [Person-Scoped Profiles Migration Guide](./V0.5.190_person-scoped-profiles-migration-guide.md)
 
 **Quick Summary**:
 - Remove all `organisation_id` filters/queries for profile tables
@@ -91,7 +125,7 @@ This guide covers:
 - Super admin permissions returning false
 - Potential data leakage between organisations
 
-**Migration**: [Organisation Context Timing Fix](./organisation-context-timing-fix.md)
+**Migration**: [Organisation Context Timing Fix](./V0.3.44_organisation-context-timing-fix.md)
 
 **Quick Fix**:
 ```bash
@@ -393,7 +427,7 @@ function MyComponent() {
 
 ## 🔐 RBAC Migration
 
-For detailed RBAC migration, see the [RBAC Migration Guide](./rbac-migration.md).
+For detailed RBAC migration, see the [RBAC Migration Guide](./V0.4.0_rbac-migration.md).
 
 ### Quick RBAC Migration
 
@@ -487,8 +521,20 @@ import '@jmruthers/pace-core/src/styles/core.css';
 
 ## 📚 Additional Resources
 
-- **[RBAC Migration Guide](./rbac-migration.md)** - Detailed RBAC migration
-- **[Migration Guide](./MIGRATION_GUIDE.md)** - Complete migration reference
+### Migration Guides
+
+- **[Complete Migration Guide](./MIGRATION_GUIDE.md)** - General migration patterns and best practices
+- **[v0.5.190 → v0.6.1 Migration Guide](./V0.5.190_TO_V0.6.1_MIGRATION.md)** - Comprehensive migration for v0.6.1
+- **[React 19 Migration Guide](./V0.6.0_REACT_19_MIGRATION.md)** - React 19 upgrade instructions (v0.6.0)
+- **[RBAC Migration Guide](./V0.4.0_rbac-migration.md)** - RBAC system migration (v0.4.0+)
+- **[Person-Scoped Profiles Migration](./V0.5.190_person-scoped-profiles-migration-guide.md)** - Profile migration guide (v0.5.190+)
+- **[Database Changes December 2025](./database-changes-december-2025.md)** - Database schema changes
+- **[Migration Guide](./MIGRATION_GUIDE.md)** - Comprehensive migration guide with quick reference table
+
+### Documentation
+
+- **[Documentation Structure](./DOCUMENTATION_STRUCTURE.md)** - Guidelines for CHANGELOG and migration docs
+- **[CHANGELOG.md](../../CHANGELOG.md)** - Version history and change announcements
 - **[Common Issues](../troubleshooting/common-issues.md)** - Troubleshooting migration issues
 - **[API Reference](../api-reference/)** - Complete API documentation