Skip to content

Prepare a safe change or retire a system

Review a documentation change

Purpose: prepare a reviewable Git change without absorbing unrelated work.

  1. Inspect state:
git status --short --branch
git diff --stat
git diff --check
  1. Review each changed file and identify pre-existing work.
  2. Run:
python3 scripts/docs_qa.py
mkdocs build --strict
  1. Confirm site/, caches, archives, logs, and secret-like files are not staged:
git status --short
git diff --cached --name-status
  1. Stage only intended paths if commit authorization is later given.

Risk: broad staging can absorb user work or generated output. Roll back only a known disposable file with git restore <path>; never use a destructive reset in a dirty worktree.

Record a retired or replaced system

Purpose: remove obsolete operations from the current path without erasing recovery history.

  1. Validate that the service is absent or explicitly retired.
  2. Record owner approval, date, final state, data disposition, backup location, DNS/ingress/firewall removal, and replacement.
  3. Change its lifecycle to Retired or Historical in the service catalog.
  4. Move procedures to history or add a prominent historical banner.
  5. Replace current cross-links with the supported system.
  6. Keep a compatibility page when the URL may be referenced externally.
  7. Update dependencies, inventory, network, backup, monitoring, and ADRs.
  8. Run strict validation.

Expected: a first-time administrator cannot mistake the old commands for the live environment, but can still locate recovery evidence.

Troubleshooting

  • Unknown owner/data: mark Unverified; do not delete.
  • Old URL has inbound links: preserve a compatibility page.
  • Replacement is incomplete: use lifecycle Transitional, list the exact remaining dependency and owner.

Official reference