Skip to content

Conversation

@NormB
Copy link
Owner

@NormB NormB commented Dec 30, 2025

Summary

Consolidates MIGRATION_GUIDE.md into UPGRADE_GUIDE.md to reduce documentation fragmentation and improve discoverability.

Changes

UPGRADE_GUIDE.md → "Upgrade & Migration Guide" (v2.0)

  • Added new Security Migration (AppRole & TLS) section:
    • Migration scenarios table (Fresh Install, Pre-v1.2, Adding TLS, Custom Service)
    • Root Token → AppRole migration (5 steps with verification)
    • TLS dual-mode and TLS-only mode setup
    • Adding AppRole to custom services (4-step guide)
    • Security migration rollback procedures
  • Added FAQ section covering:
    • Version upgrade questions
    • AppRole & TLS questions
    • Profile questions

Deleted Files

  • MIGRATION_GUIDE.md - Content integrated into UPGRADE_GUIDE.md

Updated References

  • docs/README.md - Updated index entry
  • docs/ROLLBACK_PROCEDURES.md - Updated cross-references

Rationale

  • MIGRATION_GUIDE.md covered AppRole/TLS migration which is a subset of upgrade procedures
  • Consolidation reduces the number of documents users need to navigate
  • Single source of truth for all upgrade and migration procedures

Test plan

  • Verify new section renders correctly in UPGRADE_GUIDE.md
  • Verify all cross-references are valid
  • Verify docs/README.md index is accurate

Merged MIGRATION_GUIDE.md into UPGRADE_GUIDE.md to reduce documentation
fragmentation and improve discoverability.

Changes:
- Renamed to "Upgrade & Migration Guide" (v2.0)
- Added "Security Migration (AppRole & TLS)" section covering:
  - Migration scenarios table
  - Root Token → AppRole migration steps
  - TLS dual-mode and TLS-only setup
  - Adding AppRole to custom services
  - Security migration rollback procedures
- Added FAQ section covering version upgrades, AppRole/TLS, and profiles
- Deleted MIGRATION_GUIDE.md (content now in UPGRADE_GUIDE.md)
- Updated docs/README.md index
- Updated ROLLBACK_PROCEDURES.md cross-references
@NormB NormB merged commit cf78d2c into main Dec 30, 2025
31 checks passed
@NormB NormB deleted the docs/consolidate-upgrade-migration branch December 30, 2025 13:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants