Deprecation policy

Updated Jul 14, 2026

When a public API element needs to change, simulacat follows a three-phase deprecation lifecycle:

  1. Introduce replacement alongside old API. The new symbol or fixture is added and documented while the old one continues to work unchanged.

  2. Emit warnings with migration guidance. The old symbol emits a SimulacatDeprecationWarning (a subclass of DeprecationWarning) that names the replacement and provides migration instructions. Consumers can filter these warnings independently:

   import warnings
   from simulacat import SimulacatDeprecationWarning

   # Turn simulacat deprecation warnings into errors during CI.
   warnings.filterwarnings("error", category=SimulacatDeprecationWarning)
  1. Remove after a documented transition period. The deprecated symbol is removed only after the transition period stated in the warning message. The removal version is recorded in DEPRECATED_APIS in simulacat/api_stability.py and announced in the changelog.

No symbols are currently deprecated.