From 79d2d01923cf66217fd5aa3a0be5ee9ea2000872 Mon Sep 17 00:00:00 2001 From: DanConwayDev Date: Fri, 23 Jan 2026 12:15:12 +0000 Subject: Generalize migration guide for any GRASP implementation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename guide: migrate-ngit-relay-to-ngit-grasp.md → migrate-to-ngit-grasp.md - Remove ngit-relay and relay.ngit.dev specific references - Use generic terminology: source/target relay, current implementation - Add Compatibility section explaining requirements - Update examples to be implementation-agnostic - Update script comments to reference GRASP relay (not ngit-relay) - Update README.md to link to the new guide Scripts already work with any GRASP implementation via parameters. --- docs/how-to/migration-scripts/01-fetch-events.sh | 4 ++-- docs/how-to/migration-scripts/10-check-git-sync.sh | 20 ++++++++++---------- docs/how-to/migration-scripts/20-categorize.sh | 4 ++-- docs/how-to/migration-scripts/21-compare-relays.sh | 4 ++-- .../migration-scripts/30-extract-parse-failures.sh | 10 +++++----- .../migration-scripts/31-extract-purgatory-expiry.sh | 10 +++++----- docs/how-to/migration-scripts/40-classify-actions.sh | 4 ++-- .../migration-scripts/run-migration-analysis.sh | 14 +++++++------- 8 files changed, 35 insertions(+), 35 deletions(-) (limited to 'docs/how-to/migration-scripts') diff --git a/docs/how-to/migration-scripts/01-fetch-events.sh b/docs/how-to/migration-scripts/01-fetch-events.sh index 6870659..e0d6f26 100755 --- a/docs/how-to/migration-scripts/01-fetch-events.sh +++ b/docs/how-to/migration-scripts/01-fetch-events.sh @@ -2,7 +2,7 @@ # # 01-fetch-events.sh - Fetch nostr events from a relay for migration analysis # -# PHASE 1 of the ngit-relay to ngit-grasp migration analysis pipeline. +# PHASE 1 of the GRASP relay to ngit-grasp migration analysis pipeline. # Fetches kind 30618 (state), 30617 (announcement), and 5 (deletion) events. # # USAGE: @@ -41,7 +41,7 @@ # - Run Phase 1 and Phase 2 back-to-back for accurate snapshot # # SEE ALSO: -# docs/how-to/migrate-ngit-relay-to-ngit-grasp.md - Full migration guide +# docs/how-to/migrate-to-ngit-grasp.md - Full migration guide # set -euo pipefail diff --git a/docs/how-to/migration-scripts/10-check-git-sync.sh b/docs/how-to/migration-scripts/10-check-git-sync.sh index 493d50a..1f2ce04 100755 --- a/docs/how-to/migration-scripts/10-check-git-sync.sh +++ b/docs/how-to/migration-scripts/10-check-git-sync.sh @@ -2,21 +2,21 @@ # # 10-check-git-sync.sh - Compare state events to actual git data on disk # -# PHASE 2 of the ngit-relay to ngit-grasp migration analysis pipeline. +# PHASE 2 of the GRASP relay to ngit-grasp migration analysis pipeline. # Compares kind 30618 state events against actual git refs on disk. # # USAGE: # ./10-check-git-sync.sh [--categorize] # # EXAMPLES: -# # Check prod relay against prod git data -# ./10-check-git-sync.sh output/prod/raw/state-events.json /var/lib/ngit-relay/git output/prod +# # Check source relay against source git data +# ./10-check-git-sync.sh output/prod/raw/state-events.json /var/lib/grasp-relay/git output/prod # -# # Check archive relay against archive git data -# ./10-check-git-sync.sh output/archive/raw/state-events.json /var/lib/ngit-relay-archive/git output/archive +# # Check target relay against target git data +# ./10-check-git-sync.sh output/archive/raw/state-events.json /var/lib/ngit-grasp/git output/archive # # # Check and categorize in one step (convenience mode) -# ./10-check-git-sync.sh output/prod/raw/state-events.json /var/lib/ngit-relay/git output/prod --categorize +# ./10-check-git-sync.sh output/prod/raw/state-events.json /var/lib/grasp-relay/git output/prod --categorize # # INPUT: # state-events.json - JSONL file from Phase 1 (01-fetch-events.sh) @@ -53,7 +53,7 @@ # - Handles packed refs (git show-ref) and loose refs # # SEE ALSO: -# docs/how-to/migrate-ngit-relay-to-ngit-grasp.md - Full migration guide +# docs/how-to/migrate-to-ngit-grasp.md - Full migration guide # 01-fetch-events.sh - Phase 1 script that produces input for this script # 20-categorize.sh - Phase 3a script that consumes output from this script # @@ -101,13 +101,13 @@ usage() { echo "" echo "Arguments:" echo " state-events.json JSONL file from Phase 1 (kind 30618 events)" - echo " git-base-dir Base directory for git repos (e.g., /var/lib/ngit-relay/git)" + echo " git-base-dir Base directory for git repos (e.g., /var/lib/grasp-relay/git)" echo " output-dir Directory to store output files" echo " --categorize Optional: also output category files (like Phase 3)" echo "" echo "Examples:" - echo " $0 output/prod/raw/state-events.json /var/lib/ngit-relay/git output/prod" - echo " $0 output/archive/raw/state-events.json /var/lib/ngit-relay-archive/git output/archive" + echo " $0 output/prod/raw/state-events.json /var/lib/grasp-relay/git output/prod" + echo " $0 output/archive/raw/state-events.json /var/lib/ngit-grasp/git output/archive" echo "" echo "Output:" echo " git-sync-status.tsv - TSV with: repo, npub, state_refs, git_refs, matches, reason" diff --git a/docs/how-to/migration-scripts/20-categorize.sh b/docs/how-to/migration-scripts/20-categorize.sh index f47eb55..b38dc00 100755 --- a/docs/how-to/migration-scripts/20-categorize.sh +++ b/docs/how-to/migration-scripts/20-categorize.sh @@ -2,7 +2,7 @@ # # 20-categorize.sh - Categorize git sync status into 4 categories # -# PHASE 3a of the ngit-relay to ngit-grasp migration analysis pipeline. +# PHASE 3a of the GRASP relay to ngit-grasp migration analysis pipeline. # Takes git-sync-status.tsv from Phase 2 and categorizes into 4 files. # # USAGE: @@ -39,7 +39,7 @@ # RUNTIME: < 1 second (local processing only) # # SEE ALSO: -# docs/how-to/migrate-ngit-relay-to-ngit-grasp.md - Full migration guide +# docs/how-to/migrate-to-ngit-grasp.md - Full migration guide # 10-check-git-sync.sh - Phase 2 script that produces input for this script # diff --git a/docs/how-to/migration-scripts/21-compare-relays.sh b/docs/how-to/migration-scripts/21-compare-relays.sh index 6b40dc8..b9c0d30 100755 --- a/docs/how-to/migration-scripts/21-compare-relays.sh +++ b/docs/how-to/migration-scripts/21-compare-relays.sh @@ -2,7 +2,7 @@ # # 21-compare-relays.sh - Compare prod vs archive category files to find gaps # -# PHASE 3b of the ngit-relay to ngit-grasp migration analysis pipeline. +# PHASE 3b of the GRASP relay to ngit-grasp migration analysis pipeline. # Compares categorized output from prod and archive to identify: # - Repos complete in prod but missing/incomplete in archive # - Repos in archive but not in prod @@ -39,7 +39,7 @@ # RUNTIME: < 1 second (local processing only) # # SEE ALSO: -# docs/how-to/migrate-ngit-relay-to-ngit-grasp.md - Full migration guide +# docs/how-to/migrate-to-ngit-grasp.md - Full migration guide # 20-categorize.sh - Phase 3a script that produces input for this script # diff --git a/docs/how-to/migration-scripts/30-extract-parse-failures.sh b/docs/how-to/migration-scripts/30-extract-parse-failures.sh index 753fd3e..bc2049a 100755 --- a/docs/how-to/migration-scripts/30-extract-parse-failures.sh +++ b/docs/how-to/migration-scripts/30-extract-parse-failures.sh @@ -2,7 +2,7 @@ # # 30-extract-parse-failures.sh - Extract parse failure events from systemd logs # -# PHASE 4a of the ngit-relay to ngit-grasp migration analysis pipeline. +# PHASE 4a of the GRASP relay to ngit-grasp migration analysis pipeline. # Extracts structured [PARSE_FAIL] log entries from journalctl. # # USAGE: @@ -42,7 +42,7 @@ # [PARSE_FAIL] log entries. Until those are implemented, this script will # find no matching entries (which is handled gracefully). # -# See: docs/how-to/migrate-ngit-relay-to-ngit-grasp.md (Dependencies section) +# See: docs/how-to/migrate-to-ngit-grasp.md (Dependencies section) # # Expected Rust logging code: # tracing::warn!( @@ -59,7 +59,7 @@ # RUNTIME: Depends on log volume, typically < 30 seconds # # SEE ALSO: -# docs/how-to/migrate-ngit-relay-to-ngit-grasp.md - Full migration guide +# docs/how-to/migrate-to-ngit-grasp.md - Full migration guide # 31-extract-purgatory-expiry.sh - Companion script for purgatory expiry logs # @@ -231,7 +231,7 @@ main() { if [[ "$sample_count" -eq 0 ]]; then log_warn "No [PARSE_FAIL] entries found in logs." log_warn "This is expected if ngit-grasp logging improvements are not yet deployed." - log_warn "See: docs/how-to/migrate-ngit-relay-to-ngit-grasp.md (Dependencies section)" + log_warn "See: docs/how-to/migrate-to-ngit-grasp.md (Dependencies section)" fi exit 0 @@ -259,7 +259,7 @@ main() { log_warn "" log_warn " [PARSE_FAIL] kind=30618 event_id=abc123 reason=\"...\" repo=myrepo npub=npub1..." log_warn "" - log_warn "See: docs/how-to/migrate-ngit-relay-to-ngit-grasp.md (Dependencies section)" + log_warn "See: docs/how-to/migrate-to-ngit-grasp.md (Dependencies section)" log_warn "" # Create empty output file with header comment diff --git a/docs/how-to/migration-scripts/31-extract-purgatory-expiry.sh b/docs/how-to/migration-scripts/31-extract-purgatory-expiry.sh index 38b2ca3..8cadad9 100755 --- a/docs/how-to/migration-scripts/31-extract-purgatory-expiry.sh +++ b/docs/how-to/migration-scripts/31-extract-purgatory-expiry.sh @@ -2,7 +2,7 @@ # # 31-extract-purgatory-expiry.sh - Extract purgatory expiry events from systemd logs # -# PHASE 4b of the ngit-relay to ngit-grasp migration analysis pipeline. +# PHASE 4b of the GRASP relay to ngit-grasp migration analysis pipeline. # Extracts structured [PURGATORY_EXPIRED] log entries from journalctl. # # USAGE: @@ -53,7 +53,7 @@ # [PURGATORY_EXPIRED] log entries. Until those are implemented, this script # will find no matching entries (which is handled gracefully). # -# See: docs/how-to/migrate-ngit-relay-to-ngit-grasp.md (Dependencies section) +# See: docs/how-to/migrate-to-ngit-grasp.md (Dependencies section) # # Expected Rust logging code: # tracing::warn!( @@ -70,7 +70,7 @@ # RUNTIME: Depends on log volume, typically < 30 seconds # # SEE ALSO: -# docs/how-to/migrate-ngit-relay-to-ngit-grasp.md - Full migration guide +# docs/how-to/migrate-to-ngit-grasp.md - Full migration guide # 30-extract-parse-failures.sh - Companion script for parse failure logs # @@ -238,7 +238,7 @@ main() { if [[ "$sample_count" -eq 0 ]]; then log_warn "No [PURGATORY_EXPIRED] entries found in logs." log_warn "This is expected if ngit-grasp logging improvements are not yet deployed." - log_warn "See: docs/how-to/migrate-ngit-relay-to-ngit-grasp.md (Dependencies section)" + log_warn "See: docs/how-to/migrate-to-ngit-grasp.md (Dependencies section)" fi exit 0 @@ -266,7 +266,7 @@ main() { log_warn "" log_warn " [PURGATORY_EXPIRED] repo=myrepo npub=npub1... reason=\"...\"" log_warn "" - log_warn "See: docs/how-to/migrate-ngit-relay-to-ngit-grasp.md (Dependencies section)" + log_warn "See: docs/how-to/migrate-to-ngit-grasp.md (Dependencies section)" log_warn "" # Create empty output file with header comment diff --git a/docs/how-to/migration-scripts/40-classify-actions.sh b/docs/how-to/migration-scripts/40-classify-actions.sh index 9fc718f..1706e47 100755 --- a/docs/how-to/migration-scripts/40-classify-actions.sh +++ b/docs/how-to/migration-scripts/40-classify-actions.sh @@ -2,7 +2,7 @@ # # 40-classify-actions.sh - Final classification of repos for migration action # -# PHASE 5 of the ngit-relay to ngit-grasp migration analysis pipeline. +# PHASE 5 of the GRASP relay to ngit-grasp migration analysis pipeline. # Combines all data sources from previous phases to produce actionable results. # # USAGE: @@ -82,7 +82,7 @@ # RUNTIME: < 5 seconds (local processing only) # # SEE ALSO: -# docs/how-to/migrate-ngit-relay-to-ngit-grasp.md - Full migration guide +# docs/how-to/migrate-to-ngit-grasp.md - Full migration guide # 01-fetch-events.sh - Phase 1 (fetch events) # 10-check-git-sync.sh - Phase 2 (git sync check) # 20-categorize.sh, 21-compare-relays.sh - Phase 3 (categorize and compare) diff --git a/docs/how-to/migration-scripts/run-migration-analysis.sh b/docs/how-to/migration-scripts/run-migration-analysis.sh index 2ba25ab..84aec2a 100755 --- a/docs/how-to/migration-scripts/run-migration-analysis.sh +++ b/docs/how-to/migration-scripts/run-migration-analysis.sh @@ -1,6 +1,6 @@ #!/usr/bin/env bash # -# run-migration-analysis.sh - Orchestrate the complete ngit-relay to ngit-grasp migration analysis +# run-migration-analysis.sh - Orchestrate the complete GRASP relay to ngit-grasp migration analysis # # This script runs all 5 phases of the migration analysis pipeline in sequence, # with proper error handling, progress reporting, and timing information. @@ -13,8 +13,8 @@ # ./run-migration-analysis.sh \ # --prod-relay wss://relay.ngit.dev \ # --archive-relay wss://archive.relay.ngit.dev \ -# --prod-git /var/lib/ngit-relay/git \ -# --archive-git /var/lib/ngit-relay-archive/git +# --prod-git /var/lib/grasp-relay/git \ +# --archive-git /var/lib/ngit-grasp/git # # USAGE: # ./run-migration-analysis.sh [options] @@ -64,12 +64,12 @@ # ./run-migration-analysis.sh \ # --prod-relay wss://relay.ngit.dev \ # --archive-relay wss://archive.relay.ngit.dev \ -# --prod-git /var/lib/ngit-relay/git \ -# --archive-git /var/lib/ngit-relay-archive/git \ +# --prod-git /var/lib/grasp-relay/git \ +# --archive-git /var/lib/ngit-grasp/git \ # --service ngit-grasp.service # # SEE ALSO: -# docs/how-to/migrate-ngit-relay-to-ngit-grasp.md - Full migration guide +# docs/how-to/migrate-to-ngit-grasp.md - Full migration guide # set -euo pipefail @@ -658,7 +658,7 @@ display_summary() { main() { parse_args "$@" - log_header "ngit-relay to ngit-grasp Migration Analysis" + log_header "GRASP Relay to ngit-grasp Migration Analysis" validate_args check_prerequisites -- cgit v1.2.3