change-impact-analysis

name	change-impact-analysis
description	Estimate blast radius before merge or deploy via dependency graphs, contract tests, and ripple modeling. Use when scoping a refactor, schema change, shared-library bump, or cross-team API revision.

Change Impact Analysis

Before changing shared code, schema, or contract, estimate who breaks and how badly. Impact analysis combines static dependency graphs, consumer-driven contracts, deployment topology, and historical churn to bound the blast radius and choose the safest rollout strategy.

Stack Baseline (2026)

Concern	Recommended
Service catalog	Backstage, Cortex, OpsLevel
Code graph	Sourcegraph, GitHub code search, Semgrep
API contracts	OpenAPI 3.1, AsyncAPI 3, gRPC, GraphQL Inspector
Contract testing	Pact 4.x, Spring Cloud Contract, Schemathesis
Schema evolution	Buf (protobuf), Confluent Schema Registry, Liquibase, Atlas
Runtime topology	OpenTelemetry service map, Kiali, Datadog SLOs
Risk scoring	CodeScene change-coupling, Konveyor static analysis
Rollout	Argo Rollouts, Flagger, LaunchDarkly, OpenFeature

When to Use

• Modifying a shared library, public API, event schema, or DB column.
• Deprecating an endpoint, capability, or service.
• Major framework or runtime upgrade affecting many services.
• Org change (team split / merge) needing ownership impact view.

Prerequisites

• Up-to-date service catalog with owners.
• API/event contracts published (OpenAPI/AsyncAPI/Proto).
• Telemetry showing actual consumers, not just declared ones.

Instructions

flowchart TD
  C[Proposed change] --> S[Static graph: code + IaC + contracts]
  C --> R[Runtime graph: traces, logs, schema-registry consumers]
  S --> M[Merge dependency graph]
  R --> M
  M --> B[Blast radius set]
  B --> Risk[Score: criticality x coupling x reversibility]
  Risk --> Plan[Rollout plan + comms + rollback]
  Plan --> V[Verify w/ contract + canary + SLO]

1. Build the graph. Combine static (Sourcegraph/Semgrep code refs, Buf/AsyncAPI consumers, IaC references) with runtime (OTel service map, schema-registry subscribers, gateway logs). Runtime overrides static for accuracy.
2. Define the change set. Symbols, endpoints, fields, topics, IaC modules touched. Mark each as breaking / non-breaking using semver and schema rules (Buf breaking, GraphQL Inspector).
3. Compute blast radius. Direct + transitive consumers within N hops. Cross-reference with service tier and SLOs.
4. Score risk = criticality (tier) x coupling (consumers) x reversibility (feature-flag, migration cost) x recent churn.
5. Plan rollout. Choose pattern: expand-and-contract, parallel run, dual write, strangler. Add contract tests, canary + SLO gates, comms to owners, rollback plan with TTL.
6. Verify. Run consumer-driven contract tests; deploy behind flag; observe SLOs and error budgets before full ramp.

# Detect breaking proto change
buf breaking --against '.git#branch=main'

# GraphQL schema diff
graphql-inspector diff schema.main.graphql schema.pr.graphql --rule=suppressRemovalOfDeprecatedField=false

# impact-report.yaml
change: "Rename field Order.totalCents -> Order.amountMinor"
breaking: true
direct_consumers: [checkout-ui, billing-svc, analytics-etl]
transitive: [data-lake.gold.orders]
tier: 1
strategy: expand-and-contract
steps:
  - publish v2 schema with both fields, dual-write
  - migrate consumers (Pact verifies each)
  - remove old field after 2 release cycles
rollback: feature flag order.amount.v2 (off by default first 7 days)

Common Pitfalls

Pitfall	Mitigation
Trusting only declared dependencies	Cross-check with runtime traces
Big-bang breaking change	Always expand-and-contract
No consumer contract coverage	Block release if Pact verification < 100%
Ignoring data consumers (BI, ML)	Include data-lake/feature-store in graph
Missing rollback plan	Required field in impact report

Output Format

• impact-report.yaml attached to PR / RFC.
• Updated dependency graph snapshot in Backstage.
• Contract test results and canary plan link.
• Owner notifications (Slack/email) per affected team.

Authoritative References

• Sam Newman, Building Microservices, 2e, O'Reilly.
• Pact Foundation docs (Pact 4.x, Pact Broker).
• Buf, "Breaking change detection" (2026 docs).
• Adam Tornhill, Software Design X-Rays (change coupling).
• ThoughtWorks Tech Radar Vol. 31 (Consumer-driven contracts = Adopt).