@jmruthers/pace-core 0.6.1 → 0.6.3

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