From 92a9a3bfe0bc522e8ae411991a366a3a6310d525 Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Tue, 3 Feb 2026 14:41:46 +0000 Subject: [PATCH] docs: archive relay.ngit.dev migration materials for reference Move migration guide and scripts to docs/archive/2026-01-relay-ngit-dev-migration/ with clear warnings that these are reference-only materials from a specific migration context, not general-purpose tools. These materials document the relay.ngit.dev migration from ngit-relay to ngit-grasp in January 2026. The scripts were developed iteratively during the migration and are specific to that context. They are preserved for: - Historical reference - Context for production fixes in this branch - Inspiration for future migrations (not direct reuse) The migration uncovered critical bugs now fixed in this branch: - Git protocol error handling - Naughty list false positives - Purgatory event tracking - Sync startup issues - Configuration management --- .../README.md | 61 +++++++++++++++++++ .../migration-guide.md} | 0 .../scripts}/01-fetch-events.sh | 0 .../scripts}/10-check-git-sync.sh | 0 .../scripts}/20-categorize.sh | 0 .../scripts}/21-compare-relays.sh | 0 .../scripts}/22-compare-git-data.sh | 0 .../scripts}/30-extract-parse-failures.sh | 0 .../scripts}/31-extract-purgatory-expiry.sh | 0 .../scripts}/40-classify-actions.sh | 0 .../scripts}/run-migration-analysis.sh | 0 .../scripts}/validate-service.sh | 0 docs/how-to/README.md | 12 ---- 13 files changed, 61 insertions(+), 12 deletions(-) create mode 100644 docs/archive/2026-01-relay-ngit-dev-migration/README.md rename docs/{how-to/migrate-to-ngit-grasp.md => archive/2026-01-relay-ngit-dev-migration/migration-guide.md} (100%) rename docs/{how-to/migration-scripts => archive/2026-01-relay-ngit-dev-migration/scripts}/01-fetch-events.sh (100%) rename docs/{how-to/migration-scripts => archive/2026-01-relay-ngit-dev-migration/scripts}/10-check-git-sync.sh (100%) rename docs/{how-to/migration-scripts => archive/2026-01-relay-ngit-dev-migration/scripts}/20-categorize.sh (100%) rename docs/{how-to/migration-scripts => archive/2026-01-relay-ngit-dev-migration/scripts}/21-compare-relays.sh (100%) rename docs/{how-to/migration-scripts => archive/2026-01-relay-ngit-dev-migration/scripts}/22-compare-git-data.sh (100%) rename docs/{how-to/migration-scripts => archive/2026-01-relay-ngit-dev-migration/scripts}/30-extract-parse-failures.sh (100%) rename docs/{how-to/migration-scripts => archive/2026-01-relay-ngit-dev-migration/scripts}/31-extract-purgatory-expiry.sh (100%) rename docs/{how-to/migration-scripts => archive/2026-01-relay-ngit-dev-migration/scripts}/40-classify-actions.sh (100%) rename docs/{how-to/migration-scripts => archive/2026-01-relay-ngit-dev-migration/scripts}/run-migration-analysis.sh (100%) rename docs/{how-to/migration-scripts => archive/2026-01-relay-ngit-dev-migration/scripts}/validate-service.sh (100%) 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