Migration Checklist: Converting Safely Without Stalling Delivery

Phase 0: inventory and risk profiling

Before changing libraries, quantify migration exposure. Count where compatibility-only patterns exist, where reporting controls are fragile, and where factory overrides are deeply path-dependent.

[UVM] migration inventory template

  Module/VIP          Legacy alias use   Factory complexity   Reporting complexity   Owner
  --------------------------------------------------------------------------------------------
  axi_vip             high               high                 medium                 team_axi
  apb_vip             medium             low                  low                    team_apb
  soc_env             medium             high                 high                   team_soc
  scoreboards         low                low                  high                   team_chk

1. Tag all high-complexity modules with dedicated migration owners.

2. Define strict-lane target date per subsystem, not one global date.

3. Create a migration scorecard reviewed weekly by DV and CAD leads.

Phase 1: establish dual-lane CI

The first deliverable is observability, not cleanup. Add strict and compatibility lanes with identical fixed-seed testlists and signature capture.

[ADV] CI gate progression

  Gate G1: compat lane required, strict lane informational
  Gate G2: strict lane required for touched files/subsystems
  Gate G3: strict lane required globally for merge
  Gate G4: strict-only for all maintained branches

# Example staged gating controls
make ci GATE=G1
make ci GATE=G2 SCOPE=touched
make ci GATE=G3
make ci GATE=G4

• Use gate flags to avoid all-or-nothing migration paralysis.

• Keep compatibility lane temporarily for rollback confidence.

• Publish gate definitions so engineers know exact merge criteria.

Phase 2: refactor high-yield classes first

Prioritize changes that collapse many failures at once: reporting ID normalization, explicit severity actions, deterministic factory overrides, and removal of compatibility-only helper APIs in shared base classes.

[UVM] high-yield remediation backlog

  Bucket                         Typical win size
  -------------------------------------------------------------
  Report ID normalization        10-30% signature stability gain
  Explicit verbosity policy      5-15% log noise reduction
  Factory override cleanup       10-25% behavior drift reduction
  Legacy helper replacement      15-35% strict compile failures removed

// Example: centralize reporting setup in shared base component
class tb_base_component extends uvm_component;
  `uvm_component_utils(tb_base_component)

  function void apply_report_policy();
    set_report_id_verbosity("CFG", UVM_LOW);
    set_report_id_verbosity("SCB", UVM_MEDIUM);
    set_report_severity_action(UVM_ERROR, UVM_DISPLAY | UVM_COUNT);
  endfunction
endclass

Refactor ordering heuristic

1. Shared base classes and utilities first.

2. High-fanout VIP packages second.

3. Leaf tests and one-off benches last.

Phase 3+: sustainment, rollback, and signoff

Migration is complete only when regression health remains stable without manual babysitting. Add policy checks, ownership alerts, and rollback-safe releases.

[ADV] signoff dashboard fields

  Metric                               Target for signoff
  -----------------------------------------------------------------------
  Strict lane pass rate                >= 99% on fixed-seed smoke matrix
  New compatibility-only callsites     0 per week
  Mean strict failure triage time      < 2 business days
  Factory/reporting drift incidents    trending to zero for 4 weeks
  Cross-vendor strict parity           stable across supported simulators

[UVM] rollback-safe release model

  Release Rn:
    - strict lane required
    - compatibility lane retained for one cycle as emergency fallback
  Release Rn+1:
    - compatibility lane removed from default CI
    - fallback kept in archived pipeline only

• Define who can authorize temporary fallback to compatibility mode.

• Require postmortem for every fallback invocation.

• Keep migration playbook versioned and reusable for future methodology upgrades.

Key takeaways

• Successful migration is phased: inventory, observability, remediation, sustainment.

• Dual-lane CI with progressive gates prevents both chaos and stagnation.

• Focus first on high-yield shared patterns to reduce failures quickly.

• Signoff requires sustained strict stability, not one green week.

Common pitfalls

• Switching to strict-only before teams have triage visibility.

• Declaring victory without a policy to prevent reintroduction of legacy APIs.

• Relying on hero debugging instead of taxonomy-driven closure loops.