Deprecation Policy

Auto-generated mirror. This page mirrors docs/deprecation-calendar.md, the canonical source of truth. Do not edit this file directly; edit docs/deprecation-calendar.md and re-run scripts/wiki/sync_mirrors.py.

Deprecation calendar

Status: NORMATIVE (v0.9.7+).

Scope: enumerates every active deprecation on Evidentia's public surface (CLI flags, env vars, library entry points, REST URIs, model fields, EventAction values, plugin contract methods, MCP tool names). Operators MAY rely on a deprecated surface continuing to work until the target removal release.

Canonical location: docs/deprecation-calendar.md. Cross-references: api-stability.md (deprecation policy section), CHANGELOG.md per-release Deprecated / Removed blocks.

---

Active deprecations

Surface	Replacement	Deprecated since	Target removal	Notes
evidentia conmon check --last-completed-file (CLI flag)	--state-file	v0.9.6 (2026-05-18)	v1.0.0	Normalized to match conmon watch, conmon health, conmon mark-completed. DeprecationWarning emitted when used; specifying both flags exits with code 2.
evidentia_core.models.finding.SecurityFinding (library class name)	evidentia_core.models.finding.Finding (same class, new canonical name)	v0.10.1 (2026-05-23)	v1.0.0 (earliest major bump)	The SecurityFinding name is kept as a backward-compatible alias for ≥ 1 minor cycle per the deprecation policy. Both names refer to the same class — no runtime difference, no behavior change, isinstance(obj, SecurityFinding) and isinstance(obj, Finding) both succeed. The rename aligns with OCSF's "Finding" terminology (Compliance Finding, Detection Finding). No DeprecationWarning is emitted in v0.10.1 to avoid spamming the ~50+ existing call sites — the alias is silent. Operators / integrators are encouraged to switch to Finding in new code; existing code keeps working unchanged.

No other surfaces are currently deprecated as of v0.10.1.

---

Recently removed (history)

No surfaces removed yet — this is the first deprecation calendar revision. Future removals (each tied to a major-version bump) will be listed here for ≥ 2 minor releases past the removal so operators searching their CHANGELOG can find the trail.

---

How removals are sequenced

Per the api-stability.md deprecation policy:

1. Announce in release N: add DeprecationWarning (Python), Deprecation: true header (REST), CHANGELOG entry under "Deprecated". Add a row to this calendar.
2. Maintain through release N+1: surface continues to work unchanged. Warning continues to emit.
3. Remove in release N+2 (≥ major-bump release): drop the surface; CHANGELOG entry under "Removed"; move calendar row to "Recently removed" history.

The minimum window between announce and remove is 1 full minor release cycle (release N → N+1 → N+2). Practical removal windows are typically longer to give operators time to migrate.

---

Process for proposing a new deprecation

1. Open a PR adding the surface to the "Active deprecations" table above with the proposed target removal release.
2. Update api-stability.md if the surface is declared frozen there.
3. Add the deprecation announcement in the implementing release's CHANGELOG under "Deprecated".
4. Wire the DeprecationWarning (Python) or Deprecation: true header (REST) in code.
5. Add a regression test that EXERCISES the deprecated surface AND asserts the warning fires (preserves the deprecation path's testability through the maintenance window).

---

Why this calendar exists

Operators integrating Evidentia in production GRC pipelines need predictability about when they MUST migrate code paths. Listing every active deprecation in one canonical place — with target removal release and replacement — closes one of the open v1.0 acceptance gates per docs/v1.0-transition.md ("Deprecation calendar published for any v0.9.x → v1.0 changes").

The calendar is binding under the v0.9.7 NORMATIVE api-stability contract: Evidentia will not remove a surface listed here earlier than its declared target removal release. Pushing a removal later (extending the maintenance window) is non-breaking and may happen when operator feedback surfaces.