Änderungsfolgen und Kompatibilität

Compatibility & Change Impact Analysis

A refactoring that compiles locally can still break external API consumers, in-flight background jobs, cached payloads, database rolling deployments or dynamic framework bindings. Evaluate every boundary crossed by the change before altering signatures or structures.

1. Contract & Boundary Inventory

Check every surface where the modified code interacts with the outside world or persisted state:

• Public & internal APIs: HTTP endpoints, GraphQL fields, RPC methods, WebSocket/IPC messages, CLI flags and exit codes, and exported package symbols.
• Persisted & in-flight data:
  • Database columns, JSONB blobs, enum values and migration compatibility with currently running code.
  • Queued job payloads, scheduled task parameters and event-bus messages already waiting in Redis/brokers during deployment.
  • Browser localStorage/IndexedDB, mobile client caches and server-side cache entries written by the previous version.
• Configuration & environment contracts: environment variable names, config file schemas, feature flag keys and default values.

2. Expand-and-Contract Across Version Boundaries

When a contract must change across services, clients or persisted state, never make an abrupt breaking swap in a single step:

1. Expand (Dual Support):
   • Accept both the old and new input formats/parameters (e.g., read new field with fallback to legacy field).
   • Emit or populate backward-compatible outputs so existing consumers continue working.
2. Migrate Consumers & State:
   • Update internal callers, frontend/mobile clients or background job producers to use the new contract.
   • Backfill or migrate persisted records and drain in-flight legacy queue payloads.
3. Contract (Clean Removal):
   • Remove the compatibility adapter, alias or deprecated field only after verifying that all consumers and persisted payloads have transitioned.

3. Error, Side-Effect & Performance Parity

Preserve operational invariants that callers implicitly rely on:

• Error semantics: keep HTTP status codes, domain error codes, exception types and retryability classifications stable unless an explicit contract change is agreed.
• Idempotency & transaction boundaries: splitting a function must not accidentally move a database write outside its transaction or cause an external side effect to fire twice on retry.
• Performance & algorithmic complexity: ensure decomposing a module does not replace a single batched query with an $N+1$ loop across an abstraction boundary or introduce unnecessary deep cloning on hot paths.

4. Rollout Ordering & Rollback Safety

• Determine whether the change is single-commit safe (purely internal with all callers updated atomically) or requires a multi-stage transition (schema -> code -> backfill -> cleanup).
• Verify that if the deployment is rolled back to the previous version, existing data and in-flight jobs remain readable.
• Document any temporary compatibility shims, deprecation notices and the concrete condition for removing them, and align cross-cutting impacts with the architect and the technical writer.