From e7f23be6217a494c5c47f146bbab4e8c595a5ef9 Mon Sep 17 00:00:00 2001 From: Norm Brandinger Date: Tue, 30 Dec 2025 07:56:00 -0500 Subject: [PATCH] docs: archive obsolete documentation and improve cross-references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Archive historical documents to docs/archive/: - IMPROVEMENTS_2025-11-19.md (point-in-time PR summary) - NEW_TESTS_SUMMARY.md (historical test addition summary) - PHASE_4_SUMMARY.md (phase completion report) - TEST_VALIDATION_REPORT.md (point-in-time validation report) - Add cross-references between related documents: - UPGRADE_GUIDE.md ↔ MIGRATION_GUIDE.md - DISASTER_RECOVERY.md ↔ ROLLBACK_PROCEDURES.md - All guides now link to related troubleshooting docs - Update docs/README.md: - Remove references to archived documents - Update documentation coverage table - Add note about archive location - Update document dates and version numbers --- docs/DISASTER_RECOVERY.md | 7 +++++ docs/MIGRATION_GUIDE.md | 9 ++++-- docs/README.md | 28 ++++++------------- docs/ROLLBACK_PROCEDURES.md | 12 ++++---- docs/UPGRADE_GUIDE.md | 7 ++++- docs/{ => archive}/IMPROVEMENTS_2025-11-19.md | 0 docs/{ => archive}/NEW_TESTS_SUMMARY.md | 0 docs/{ => archive}/PHASE_4_SUMMARY.md | 0 docs/{ => archive}/TEST_VALIDATION_REPORT.md | 0 9 files changed, 35 insertions(+), 28 deletions(-) rename docs/{ => archive}/IMPROVEMENTS_2025-11-19.md (100%) rename docs/{ => archive}/NEW_TESTS_SUMMARY.md (100%) rename docs/{ => archive}/PHASE_4_SUMMARY.md (100%) rename docs/{ => archive}/TEST_VALIDATION_REPORT.md (100%) diff --git a/docs/DISASTER_RECOVERY.md b/docs/DISASTER_RECOVERY.md index 4801662..167c1a6 100644 --- a/docs/DISASTER_RECOVERY.md +++ b/docs/DISASTER_RECOVERY.md @@ -2,6 +2,13 @@ Step-by-step procedures for recovering from infrastructure failures, including complete environment loss, Vault data loss, database corruption, and network issues. Target RTO: 30 minutes. +**Last Updated:** 2025-12-30 + +> **Related Documentation:** +> - For rolling back upgrades or changes, see [ROLLBACK_PROCEDURES.md](./ROLLBACK_PROCEDURES.md) +> - For upgrade procedures, see [UPGRADE_GUIDE.md](./UPGRADE_GUIDE.md) +> - For troubleshooting, see [TROUBLESHOOTING.md](./TROUBLESHOOTING.md) + ## Table of Contents - [Overview](#overview) diff --git a/docs/MIGRATION_GUIDE.md b/docs/MIGRATION_GUIDE.md index 53edf61..dd8d59d 100644 --- a/docs/MIGRATION_GUIDE.md +++ b/docs/MIGRATION_GUIDE.md @@ -1,8 +1,13 @@ # Migration Guide -Step-by-step instructions for migrating from legacy configurations to DevStack Core v1.3.0+, including AppRole authentication and service profiles. +Step-by-step instructions for migrating from legacy configurations to DevStack Core v1.3.0+, including AppRole authentication and TLS encryption. -**Version:** 1.0 | **Last Updated:** November 19, 2025 +**Version:** 1.1 | **Last Updated:** 2025-12-30 + +> **Related Documentation:** +> - For version upgrades and service upgrades, see [UPGRADE_GUIDE.md](./UPGRADE_GUIDE.md) +> - For disaster recovery procedures, see [DISASTER_RECOVERY.md](./DISASTER_RECOVERY.md) +> - For detailed rollback procedures, see [ROLLBACK_PROCEDURES.md](./ROLLBACK_PROCEDURES.md) --- diff --git a/docs/README.md b/docs/README.md index a9144d8..94de776 100644 --- a/docs/README.md +++ b/docs/README.md @@ -91,8 +91,9 @@ This directory contains comprehensive documentation for the DevStack Core projec - Test environment setup - Test execution guidelines - Coverage goals and metrics + - 571+ tests across 50 bash scripts -- **[RUST_API_TESTING_GUIDE.md](./RUST_API_TESTING_GUIDE.md)** - Rust HTTP API testing guide (NEW) +- **[RUST_API_TESTING_GUIDE.md](./RUST_API_TESTING_GUIDE.md)** - Rust HTTP API testing guide - Comprehensive Actix-web testing patterns - Unit tests vs integration tests organization - Testing best practices (positive, negative, edge cases) @@ -100,18 +101,6 @@ This directory contains comprehensive documentation for the DevStack Core projec - Async testing with tokio and actix_rt - Production-ready testing patterns -- **[TEST_VALIDATION_REPORT.md](./TEST_VALIDATION_REPORT.md)** - Phase 0-2 validation results (NEW - Nov 2025) - - 100% test pass rate confirmation (494+ tests) - - Issues found and resolved during validation - - Performance metrics and security validation - - Production readiness assessment - -- **[NEW_TESTS_SUMMARY.md](./NEW_TESTS_SUMMARY.md)** - Extended test suite summary - - New test suites added to the project - - Coverage of Vault, PostgreSQL, PgBouncer, Observability - - 40+ new test cases across 4 suites - - Test statistics and implementation details - ### Architecture & Design - **[ARCHITECTURE.md](./ARCHITECTURE.md)** - Complete architecture deep-dive @@ -328,19 +317,18 @@ See [CONTRIBUTING.md](../.github/CONTRIBUTING.md) for guidelines on: | Category | Files | Status | |----------|-------|--------| -| Project Information | 1 | ✅ Complete | +| Getting Started | 4 | ✅ Complete | | Security | 2 | ✅ Complete | -| Testing | 4 | ✅ Complete | +| Testing | 2 | ✅ Complete | | Architecture | 1 | ✅ Complete | -| Service Profiles (v1.3) | 3 | ✅ Complete | -| Operational Guides | 9 | ✅ Complete | -| Upgrade Procedures | 1 | ✅ Complete | +| Service Profiles | 3 | ✅ Complete | +| Operational Guides | 12 | ✅ Complete | | API Patterns | 1 | ✅ Complete | | Reference Apps | 6 | ✅ Complete | | VoIP Infrastructure | 3 | ✅ Complete (voip/ subdirectory) | -| **Total Core Documentation Files** | **~31** | **✅ 99% Coverage** | +| **Total Core Documentation Files** | **~34** | **✅ Complete** | -**Note:** Work-in-progress files (task tracking, test results) are now located in `docs/.private/` (gitignored). +**Note:** Historical phase summaries and test reports are archived in `docs/archive/`. Work-in-progress files are in `docs/.private/` (gitignored). ## Useful Resources diff --git a/docs/ROLLBACK_PROCEDURES.md b/docs/ROLLBACK_PROCEDURES.md index 0d5315a..fa818dc 100644 --- a/docs/ROLLBACK_PROCEDURES.md +++ b/docs/ROLLBACK_PROCEDURES.md @@ -2,7 +2,12 @@ Procedures for safely rolling back DevStack Core changes, including database restores, service reverts, and configuration recovery. -**Document Version:** 1.0 | **Created:** November 14, 2025 +**Document Version:** 1.1 | **Last Updated:** 2025-12-30 + +> **Related Documentation:** +> - For disaster recovery (complete environment loss), see [DISASTER_RECOVERY.md](./DISASTER_RECOVERY.md) +> - For upgrade procedures, see [UPGRADE_GUIDE.md](./UPGRADE_GUIDE.md) +> - For AppRole/TLS migration rollback, see [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) --- @@ -26,7 +31,6 @@ This document provides step-by-step procedures to roll back DevStack Core improv - **Quick validation:** `./tests/test-rollback-simple.sh` (⭐ Recommended - 30 seconds) - **Comprehensive:** `./tests/test-rollback-comprehensive.sh` (All databases - 2 minutes) - **All test scripts:** See [Rollback Testing](#rollback-testing) section below -- **Test results:** [TEST_VALIDATION_REPORT.md](./TEST_VALIDATION_REPORT.md) ### When to Roll Back @@ -626,8 +630,6 @@ DevStack Core includes **4 automated rollback test scripts** to validate rollbac **Recommended Test:** Use `test-rollback-simple.sh` for validation - it's proven to work and validates core rollback procedures (AppRole ↔ Root Token migration). -**Latest Test Results:** See [TEST_VALIDATION_REPORT.md](./TEST_VALIDATION_REPORT.md) for comprehensive testing analysis. - ### Running Rollback Tests ```bash @@ -667,7 +669,7 @@ The following improvements have been implemented in test scripts: - Prerequisites validation before test execution - Automated cleanup on test failures -See [TEST_VALIDATION_REPORT.md](./TEST_VALIDATION_REPORT.md) for detailed test results and analysis. +See [TESTING_APPROACH.md](./TESTING_APPROACH.md) for test methodology and [tests/TEST_COVERAGE.md](../tests/TEST_COVERAGE.md) for detailed coverage analysis. ### Pre-Rollback Test diff --git a/docs/UPGRADE_GUIDE.md b/docs/UPGRADE_GUIDE.md index 04c6d3a..88b5be3 100644 --- a/docs/UPGRADE_GUIDE.md +++ b/docs/UPGRADE_GUIDE.md @@ -1,10 +1,15 @@ # Upgrade Guide **Version:** 1.3.0 -**Last Updated:** 2025-01-18 +**Last Updated:** 2025-12-30 Complete guide for upgrading DevStack Core versions, service versions, and migrating between profiles. +> **Related Documentation:** +> - For AppRole and TLS migration specifically, see [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) +> - For disaster recovery procedures, see [DISASTER_RECOVERY.md](./DISASTER_RECOVERY.md) +> - For detailed rollback procedures, see [ROLLBACK_PROCEDURES.md](./ROLLBACK_PROCEDURES.md) + --- ## Table of Contents diff --git a/docs/IMPROVEMENTS_2025-11-19.md b/docs/archive/IMPROVEMENTS_2025-11-19.md similarity index 100% rename from docs/IMPROVEMENTS_2025-11-19.md rename to docs/archive/IMPROVEMENTS_2025-11-19.md diff --git a/docs/NEW_TESTS_SUMMARY.md b/docs/archive/NEW_TESTS_SUMMARY.md similarity index 100% rename from docs/NEW_TESTS_SUMMARY.md rename to docs/archive/NEW_TESTS_SUMMARY.md diff --git a/docs/PHASE_4_SUMMARY.md b/docs/archive/PHASE_4_SUMMARY.md similarity index 100% rename from docs/PHASE_4_SUMMARY.md rename to docs/archive/PHASE_4_SUMMARY.md diff --git a/docs/TEST_VALIDATION_REPORT.md b/docs/archive/TEST_VALIDATION_REPORT.md similarity index 100% rename from docs/TEST_VALIDATION_REPORT.md rename to docs/archive/TEST_VALIDATION_REPORT.md