# Comparison Pages Migration Plan


**Last Updated:** 2025-11-20

## Overview

This document outlines the strategy for migrating the existing 67 comparison pages from the legacy template system to the unified template system.

## Current State

- **Total Pages:** 67 comparison pages
- **Current Templates:**
  - `compare_template_details.php` (used by ~40 pages)
  - `compare_template_nodetails.php` (used by ~27 pages)
- **Current Approach:** Manual placeholder replacement for each page

## Target State

- **Total Pages:** 67 comparison pages (same)
- **New Templates:**
  - `compare_template_unified.php` (one template for all)
  - Individual data files in `v2/data/competitors/`
- **New Approach:** Data-driven with automated page generation

## Migration Benefits

1. **Maintainability:** Single template to update vs. 67 hardcoded pages
2. **Consistency:** All pages use identical structure
3. **Speed:** 5 minutes to create new page vs. 30+ minutes
4. **Quality:** Built-in validation prevents errors
5. **Flexibility:** Easy to add new features to all pages at once

## Migration Strategy

### Phase 1: Pilot Testing (Week 1)

**Goal:** Validate unified template with 2-3 existing pages

**Pages to Migrate:**

1. `compare_clockin.php` (has Details section) - Already has example data
2. `compare_personio.php` (no Details section) - Already has example data
3. `compare_planday.php` (high-traffic page for validation)

**Tasks:**

1. Create data files for pilot pages
2. Generate new pages using unified template
3. Compare old vs. new output (pixel-perfect comparison)
4. Test schema validation
5. Performance testing (LCP, CLS)
6. Collect feedback and iterate

**Success Criteria:**

- [ ] New pages identical to old pages (visual comparison)
- [ ] Schema validates correctly
- [ ] Performance metrics maintained or improved
- [ ] No console errors
- [ ] All sections render correctly
- [ ] Details section works (expand/collapse)

**Timeline:** 2-3 days

### Phase 2: Small Batch Migration (Week 2)

**Goal:** Migrate 5 more pages to validate process at scale

**Pages to Migrate:**
5 pages with mix of:

- 3 with Details sections
- 2 without Details sections
- Mix of traffic levels (high/medium/low)

**Suggested Pages:**

1. `compare_timetac.php` (high traffic, Details)
2. `compare_papershift.php` (medium traffic, Details)
3. `compare_kenjo.php` (medium traffic, no Details)
4. `compare_factorial.php` (low traffic, Details)
5. `compare_bamboohr.php` (low traffic, no Details)

**Tasks:**

1. Extract data from existing pages (use extraction script)
2. Create data files
3. Validate data
4. Generate new pages
5. Side-by-side comparison
6. Document any issues
7. Refine process based on learnings

**Success Criteria:**

- [ ] All 5 pages migrated successfully
- [ ] Migration process documented
- [ ] Average migration time < 15 minutes per page
- [ ] No issues reported from users
- [ ] Performance maintained

**Timeline:** 3-5 days

### Phase 3: Bulk Migration (Weeks 3-4)

**Goal:** Migrate remaining pages in batches

**Approach:** Batch migration in groups of 10-15 pages per batch

**Batch 1:** Pages 8-22 (15 pages)
**Batch 2:** Pages 23-37 (15 pages)
**Batch 3:** Pages 38-52 (15 pages)
**Batch 4:** Pages 53-67 (15 pages)

**Process Per Batch:**

1. Extract data (can be parallelized)
2. Create data files
3. Validate all data files in batch
4. Generate pages
5. Automated comparison (if possible)
6. Manual spot-check 2-3 pages per batch
7. Deploy batch
8. Monitor for 24-48 hours before next batch

**Success Criteria Per Batch:**

- [ ] All pages in batch migrated
- [ ] Data validation passed
- [ ] Spot-checks successful
- [ ] No user-reported issues
- [ ] Performance maintained

**Timeline:** 2-3 weeks (allowing monitoring time between batches)

### Phase 4: Cleanup & Deprecation (Week 5)

**Goal:** Finalize migration and deprecate legacy templates

**Tasks:**

1. Verify all 67 pages migrated
2. Rename legacy templates:
   - `compare_template_details.php` → `compare_template_details_legacy.php`
   - `compare_template_nodetails.php` → `compare_template_nodetails_legacy.php`
3. Add deprecation notices to legacy templates
4. Update all documentation
5. Archive migration documentation
6. Celebrate! 🎉

**Success Criteria:**

- [ ] All 67 pages using unified template
- [ ] Legacy templates deprecated
- [ ] Documentation updated
- [ ] No outstanding issues

**Timeline:** 2-3 days

## Rollback Plan

### If Issues Detected

**Minor Issues (non-breaking):**

- Document issue
- Continue migration
- Fix in next template update (all pages benefit)

**Major Issues (breaking, affects functionality):**

- Pause migration
- Investigate root cause
- Fix unified template or data structure
- Re-test pilot pages
- Resume migration once fixed

**Critical Issues (site down, major bugs):**

- Immediately rollback affected pages to legacy version
- Keep old page files as backup during migration
- Investigate and fix
- Re-migrate after fix validated

### Rollback Procedure

1. Restore old page file from backup
2. Clear any caches
3. Test restored page
4. Document issue for later fix
5. Continue with other pages (pause if systematic issue)

## Testing Checklist

For each migrated page:

### Visual Comparison

- [ ] Hero section identical
- [ ] Logos display correctly
- [ ] Rating stars match
- [ ] Comparison grid layout identical
- [ ] Pricing section identical
- [ ] Details section behavior matches (if applicable)
- [ ] FAQ section identical
- [ ] Footer identical

### Functional Testing

- [ ] Page loads without errors
- [ ] All images load
- [ ] Links work correctly
- [ ] CTA buttons functional
- [ ] Details section expands/collapses (if applicable)
- [ ] Form submissions work (if applicable)
- [ ] Mobile responsive

### Technical Validation

- [ ] No console errors
- [ ] No PHP errors
- [ ] Schema validates (Google Rich Results Test)
- [ ] Meta tags correct
- [ ] Canonical URL correct
- [ ] Performance metrics acceptable:
  - LCP < 2.5s
  - FID < 100ms
  - CLS < 0.1

### SEO Check

- [ ] Title tag unchanged
- [ ] Meta description unchanged
- [ ] H1 unchanged
- [ ] Schema identical
- [ ] Internal links preserved
- [ ] Canonical URL preserved

## Data Extraction Process

For each page to migrate:

### Step 1: Run Extraction Script

```bash
php scripts/data/extract_to_unified_format.php v2/pages/compare_{slug}.php
```

This provides guidance on what data to extract.

### Step 2: Manual Extraction

Extract the following from existing page:

**Basic Info:**

- Competitor name (from title)
- Slug (from filename)
- Category (from description)
- Focus/use case (from description)
- Target audience (from description)

**Ratings:**

- Overall rating
- Review count
- Distribution (5 levels)
- Category ratings (4 ratings)

**Content:**

- Product description
- Description heading (if custom)

**Pricing:**

- Starting price
- Currency (usually EUR)
- Unit
- All pricing plans

**Details:**

- Has Details section? (true/false)
- Button text (if applicable)
- Features list (if applicable)
- Integrations list (if applicable)
- Special characteristics (if applicable)

**FAQ:**

- FAQ title (or leave empty for auto-generation)
- All FAQ items (questions and answers)

**Schema:**

- Schema name (may differ from display name)
- Schema description

**Logo:**

- Alt text
- CSS class (if any, e.g., "brightness-0 invert")
- Image paths (160w, 320w)

### Step 3: Create Data File

```bash
cp v2/data/competitors/clockin_example.php v2/data/competitors/{slug}.php
```

Fill in extracted data.

### Step 4: Validate

```bash
php scripts/validate_competitor_data.php v2/data/competitors/{slug}.php
```

Fix any validation errors.

### Step 5: Generate Page

```bash
php scripts/generate_comparison_page.php {slug}
```

### Step 6: Compare

Open both pages side-by-side:

- Old: `v2/pages/compare_{slug}.php` (current)
- New: `v2/pages/compare_{slug}.php` (generated - backup old first!)

Compare visually and functionally.

## Automation Opportunities

### Possible Automations

1. **Data Extraction:** Partially automated with extraction script (provides guidance)
2. **Batch Validation:** Run validation on multiple data files at once
3. **Batch Generation:** Generate multiple pages in one command
4. **Visual Comparison:** Screenshot diff tool for automated comparison
5. **Schema Testing:** Automated schema validation for all pages

### Scripts to Create (Optional)

**Batch Processor:**

```bash
php scripts/batch_migrate.php compare_planday compare_timetac compare_papershift
```

**Schema Validator:**

```bash
php scripts/validate_all_schemas.php
```

**Visual Diff:**

```bash
php scripts/visual_compare.php compare_planday
```

## Risk Assessment

### Low Risk

- **Visual differences:** Minor CSS/spacing differences
- **Mitigation:** Accept minor differences if functionally equivalent

### Medium Risk

- **Schema changes:** Slight schema variations that still validate
- **Mitigation:** Validate with Google Rich Results Test before deploying

### High Risk

- **Functionality breaks:** Forms, links, or interactions break
- **Mitigation:** Thorough testing, phased rollout, immediate rollback capability
- **Prevention:** Comprehensive testing checklist, pilot phase

### Critical Risk

- **SEO impact:** Changes to titles, headings, or schema affecting rankings
- **Mitigation:** Ensure exact content preservation, validate before/after
- **Prevention:** SEO validation checklist, gradual migration with monitoring

## Monitoring Plan

### During Migration (Per Batch)

**Immediate (First 24 hours):**

- Monitor error logs for PHP/JavaScript errors
- Check Google Search Console for crawl errors
- Review analytics for traffic anomalies
- Test pages manually

**Short-term (48-72 hours):**

- Monitor search rankings for migrated pages
- Check conversion rates (form submissions, clicks)
- Review user feedback/support tickets
- Performance metrics (Core Web Vitals)

**Before Next Batch:**

- Review all metrics
- Address any issues found
- Document learnings
- Proceed if all green

### Post-Migration (All Pages)

**First Week:**

- Daily monitoring of key metrics
- Error log review
- Performance tracking
- SEO rankings check

**First Month:**

- Weekly metrics review
- Comparison vs. pre-migration baseline
- Ongoing issue tracking
- Final adjustments if needed

## Success Metrics

### Migration Speed

- Target: Average 10-15 minutes per page
- Measure: Track time for each batch

### Quality

- Target: 100% of pages pass validation
- Measure: Validation script results

### Performance

- Target: Maintain or improve Core Web Vitals
- Measure: PageSpeed Insights before/after

### SEO

- Target: No negative impact on rankings
- Measure: Google Search Console position tracking

### Stability

- Target: Zero critical bugs
- Measure: Error logs, user reports

## Communication Plan

### Internal Team

- Kickoff meeting before Phase 1
- Daily updates during active migration
- Issue reports as needed
- Completion summary

### Stakeholders

- Migration plan approval before start
- Weekly progress updates
- Completion notification with benefits summary

### Users

- No communication needed (transparent migration)
- If issues arise: status page updates

## Contingency Plans

### Issue: Migration Taking Too Long

- **Solution:** Increase batch size if process is stable, or allocate more resources

### Issue: Consistent Validation Errors

- **Solution:** Review data structure, update template, re-validate process

### Issue: Performance Degradation

- **Solution:** Profile and optimize helper functions, check for N+1 queries

### Issue: SEO Rankings Drop

- **Solution:** Immediate rollback, analyze differences, fix and re-migrate

### Issue: User-Reported Bugs

- **Solution:** Triage severity, fix critical bugs immediately, batch minor fixes

## Post-Migration Benefits

### Immediate

- Single template to maintain
- Consistent structure across all pages
- Built-in validation prevents future errors

### Short-term

- Faster creation of new comparison pages (5 min vs. 30+ min)
- Easy bulk updates (fix once, applies to all)
- Better developer experience

### Long-term

- Easier to add new features (e.g., new comparison dimensions)
- Better SEO through consistency
- Reduced technical debt
- Easier onboarding for new developers

## Timeline Summary

| Phase                   | Duration      | Pages        | Goal                 |
| ----------------------- | ------------- | ------------ | -------------------- |
| Phase 1: Pilot          | 2-3 days      | 3 pages      | Validate approach    |
| Phase 2: Small Batch    | 3-5 days      | 5 pages      | Refine process       |
| Phase 3: Bulk Migration | 2-3 weeks     | 59 pages     | Complete migration   |
| Phase 4: Cleanup        | 2-3 days      | -            | Finalize & deprecate |
| **Total**               | **4-5 weeks** | **67 pages** | **Full migration**   |

## Conclusion

This migration plan provides a structured, low-risk approach to migrating all 67 comparison pages to the unified template system. The phased approach allows for validation and course correction at each stage, minimizing risk while maximizing benefits.

**Next Step:** Review and approve this plan, then begin Phase 1 pilot testing.