Skip to main content

Upgrade and Migration

Use this page when you need the stack-level upgrade and migration model: sequencing, rollback posture, and the shared verification steps that sit above any single product.

When to use this page​

  • You are planning a stack-wide or multi-product change.
  • You need the release sequencing model before following a product-specific upgrade page.
  • You need rollback and post-check posture in one place.

Prerequisites​

  • You have read Compatibility and relevant release notes.
  • You know whether the change is stack-wide or primarily product-specific.

Upgrade model​

Safe upgrades should be:

  • compatibility-aware
  • release-note-informed
  • verified before and after change
  • explicit about rollback boundaries

Architecture / Flow​

Step-by-step procedure​

1. Start with compatibility and release notes​

Use:

2. Define the sequence clearly​

Important questions:

  • which product or docs layer moves first
  • where shared-truth publication changes
  • what the rollback boundary is if verification fails

2a. Keep the OpenTofu migration fail-closed​

Current Helpifyr OpenTofu migration truth is still owner-driven and staged:

  • JaddaHelpifyr/jhf-deployment owns the migration program and deployment-side runtime truth
  • JaddaHelpifyr/helpifyr-fabric owns only the shared alignment boundary, not runtime execution
  • this public docs page is guidance, not migration completion evidence

Until the owner repos publish verified implementation evidence, treat the migration posture as planned transition work rather than a completed platform default.

3. Keep Platform Truth in the loop​

Use shared-truth and readiness surfaces as the contract boundary during rollout:

GET /api/v1/platform/version-truth
GET /api/v1/contracts/drift
GET /api/v1/observability/readiness
GET /api/v1/recovery/readiness

4. Verify after change, not only before it​

Post-upgrade checks should include:

  • shared-truth readback
  • readiness readback
  • one representative user or operator path

Verification​

This page is being applied correctly when:

  1. upgrade sequencing is explicit
  2. rollback posture is explicit
  3. post-change verification is part of the plan rather than an afterthought

Common failure modes​

Treating an upgrade as only a version bump​

Problem:

  • shared-truth and operational impact are under-scoped.

Better path:

  • include compatibility, sequencing, rollback, and verification together

Planning rollback without defining the boundary​

Problem:

  • the team knows it should rollback but not what state can be safely reversed.

Better path:

  • state the rollback boundary before execution

Source Truth​

Next paths​