# Plugin Compatibility Policy

## Versioning

`honestroles` plugin compatibility is governed by plugin API versions, not by plugin package versions.

- Core exposes `SUPPORTED_PLUGIN_API_VERSION` (currently `1.0`)
- Plugins declare `PluginSpec.api_version`

## Compatibility Rules

Registration is allowed only when:

1. Plugin major version equals core major version.
2. Plugin minor version is less than or equal to core minor version.

Examples with core `1.0`:

- `1.0`: compatible
- `1`: compatible (normalized to `1.0`)
- `1.1`: incompatible (plugin requires newer API)
- `2.0`: incompatible (breaking major mismatch)

## Deprecation

When introducing behavior changes:

1. Add warnings in one minor release.
2. Keep previous behavior working through the deprecation window.
3. Remove only in next major version.

## Plugin Maintainer Checklist

Before releasing a plugin:

1. Pin and test against supported `honestroles` versions.
2. Declare `PluginSpec` explicitly.
3. Run plugin contract tests with representative fixtures.
4. Avoid mutating input DataFrames in-place unless explicitly documented.

## Core Maintainer Checklist

Before releasing `honestroles`:

1. Run plugin compatibility tests.
2. Review any API changes impacting plugin signatures.
3. Update `docs/plugins/api_contract.md` and migration notes.
4. Bump major version for plugin API breaking changes.
