diff --git a/docs/archive/2026-01-relay-ngit-dev-migration/README.md b/docs/archive/2026-01-relay-ngit-dev-migration/README.md new file mode 100644 index 0000000..424067c --- /dev/null +++ b/docs/archive/2026-01-relay-ngit-dev-migration/README.md @@ -0,0 +1,61 @@ +# relay.ngit.dev Migration Archive (January 2026) + +**Status:** Reference only - not maintained + +This directory contains the migration guide and scripts used during the +relay.ngit.dev migration from ngit-relay to ngit-grasp in January 2026. + +## ⚠️ Important + +These materials are **archived for reference only**: + +- **Scripts are specific to the relay.ngit.dev migration context** +- **Not designed for general use or other migrations** +- **May not work without modification** +- **Not maintained or supported** + +Do not expect these scripts to work out of the box for your migration. + +## What's Here + +- `migration-guide.md` - Lessons learned, approach, and context from the actual migration +- `scripts/` - Analysis and validation scripts used during the migration process + +## Why Archive This? + +The relay.ngit.dev migration uncovered numerous bugs and edge cases that resulted +in critical production fixes. See commits in the `4bc5-relay-ngit-dev-migration-v2` +branch for details. + +These materials document: + +- Real-world migration challenges encountered +- Debugging approaches that worked in practice +- Context for production fixes merged from this branch +- Iterative script development during active migration + +## Using This as Reference + +If you're planning a migration to ngit-grasp: + +1. **Read the migration guide** for conceptual approach and lessons learned +2. **Review the scripts** to understand what kinds of analysis were needed +3. **Expect to write your own scripts** tailored to your specific context +4. **Test extensively** in a non-production environment first + +These materials show what was needed for one specific migration, not a +general-purpose migration toolkit. + +## Context + +This migration was completed in January 2026 and resulted in relay.ngit.dev +running ngit-grasp in production. The branch containing these materials also +includes critical fixes for: + +- Git protocol error handling +- Naughty list false positives +- Purgatory event tracking +- Sync startup issues +- Configuration management + +Those fixes are now part of the main codebase. diff --git a/docs/how-to/migrate-to-ngit-grasp.md b/docs/archive/2026-01-relay-ngit-dev-migration/migration-guide.md similarity index 100% rename from docs/how-to/migrate-to-ngit-grasp.md rename to docs/archive/2026-01-relay-ngit-dev-migration/migration-guide.md diff --git a/docs/how-to/migration-scripts/01-fetch-events.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/01-fetch-events.sh similarity index 100% rename from docs/how-to/migration-scripts/01-fetch-events.sh rename to docs/archive/2026-01-relay-ngit-dev-migration/scripts/01-fetch-events.sh diff --git a/docs/how-to/migration-scripts/10-check-git-sync.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/10-check-git-sync.sh similarity index 100% rename from docs/how-to/migration-scripts/10-check-git-sync.sh rename to docs/archive/2026-01-relay-ngit-dev-migration/scripts/10-check-git-sync.sh diff --git a/docs/how-to/migration-scripts/20-categorize.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/20-categorize.sh similarity index 100% rename from docs/how-to/migration-scripts/20-categorize.sh rename to docs/archive/2026-01-relay-ngit-dev-migration/scripts/20-categorize.sh diff --git a/docs/how-to/migration-scripts/21-compare-relays.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/21-compare-relays.sh similarity index 100% rename from docs/how-to/migration-scripts/21-compare-relays.sh rename to docs/archive/2026-01-relay-ngit-dev-migration/scripts/21-compare-relays.sh diff --git a/docs/how-to/migration-scripts/22-compare-git-data.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/22-compare-git-data.sh similarity index 100% rename from docs/how-to/migration-scripts/22-compare-git-data.sh rename to docs/archive/2026-01-relay-ngit-dev-migration/scripts/22-compare-git-data.sh diff --git a/docs/how-to/migration-scripts/30-extract-parse-failures.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/30-extract-parse-failures.sh similarity index 100% rename from docs/how-to/migration-scripts/30-extract-parse-failures.sh rename to docs/archive/2026-01-relay-ngit-dev-migration/scripts/30-extract-parse-failures.sh diff --git a/docs/how-to/migration-scripts/31-extract-purgatory-expiry.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/31-extract-purgatory-expiry.sh similarity index 100% rename from docs/how-to/migration-scripts/31-extract-purgatory-expiry.sh rename to docs/archive/2026-01-relay-ngit-dev-migration/scripts/31-extract-purgatory-expiry.sh diff --git a/docs/how-to/migration-scripts/40-classify-actions.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/40-classify-actions.sh similarity index 100% rename from docs/how-to/migration-scripts/40-classify-actions.sh rename to docs/archive/2026-01-relay-ngit-dev-migration/scripts/40-classify-actions.sh diff --git a/docs/how-to/migration-scripts/run-migration-analysis.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/run-migration-analysis.sh similarity index 100% rename from docs/how-to/migration-scripts/run-migration-analysis.sh rename to docs/archive/2026-01-relay-ngit-dev-migration/scripts/run-migration-analysis.sh diff --git a/docs/how-to/migration-scripts/validate-service.sh b/docs/archive/2026-01-relay-ngit-dev-migration/scripts/validate-service.sh similarity index 100% rename from docs/how-to/migration-scripts/validate-service.sh rename to docs/archive/2026-01-relay-ngit-dev-migration/scripts/validate-service.sh diff --git a/docs/how-to/README.md b/docs/how-to/README.md index f755be1..087ae53 100644 --- a/docs/how-to/README.md +++ b/docs/how-to/README.md @@ -110,18 +110,6 @@ How-to guides are **recipes** that show you how to solve specific problems or ac --- -### [Migrate to ngit-grasp](migrate-to-ngit-grasp.md) -**Status:** ✅ Available - -**Problem:** Switch from another GRASP implementation -**You'll learn:** -- Analyze existing relay data -- Identify repositories needing attention -- Run migration analysis scripts -- Plan and execute cutover - ---- - ## How to Use How-To Guides 1. **Find your problem** - Browse or search for what you need