ADFA-1713: Add Plugin API changelog (YY.WW capability history)

[hal-eisen-adfa]

What

Adds a Plugin API changelog — a version-mapped history of which YY.WW release first shipped each plugin capability — so a plugin developer can choose a correct plugin.min_ide_version.

Docs only. No code changes.

Why

Plugins declare plugin.min_ide_version in YY.WW form, and 26.28 (ADFA-3588) now enforces it at install. But there was no public record of when each capability appeared, so a developer had no basis for choosing the value. ADFA-1713 was blocked on exactly this document.

Changes

• docs/PLUGIN_API_CHANGELOG.md (new) — 14 changes across 10 releases, 26.02 (Sep 2025) → 26.30 (Jul 2026). Every change so far is additive. Ends with the one-liner to regenerate it each release.
• docs/plugin-api.md — corrected the stale "no binary-compat validator" follow-up (the ABI dump + validator landed in 26.28); linked the changelog from Related.
• docs/PLUGIN_AUTHORING.md — pointed the plugin.min_ide_version manifest field at the changelog.

How it was built (and stays current)

The public surface is a checked-in, validator-enforced ABI dump (plugin-api/api/plugin-api.api) as of 26.28, so each release's additions are a mechanical diff. Pre-26.28 predates the dump and was diff-verified from plugin-api/src commit history. Version mapping:

git tag --list --contains <sha> | grep -E '^[0-9]{2}\.[0-9]{2}$' | sort -V | head -1

Notes for review

• The [verified] / [reconstructed] markers distinguish entries read from the ABI dump (26.28+) from those diffed out of source history (earlier).
• The plugin.min_ide_version / plugin.max_ide_version manifest keys have existed since genesis (26.02); ADFA-3588 (26.28) is the separate enforcement + ABI-baseline milestone.
• Open question (out of scope here): max_ide_version is parsed but not enforced today — worth deciding before developers are told to rely on it.

Refs ADFA-1713.

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}

[coderabbitai]

📝 Walkthrough

• Added a version-mapped Plugin API changelog covering 14 additive capabilities across releases 26.02–26.30.
• Documented guidance for selecting plugin.min_ide_version and parsing plugin.max_ide_version.
• Updated plugin authoring documentation to reference the changelog.
• Documented ABI dumps and Kotlin binary compatibility validation introduced in 26.28.
• Added verification markers, historical-source caveats, and changelog regeneration instructions.
• Documentation-only changes; no code modifications.
• Risk: early capability history was reconstructed from source-history diffs because ABI dumps were unavailable before 26.28.

Walkthrough

Adds a version-mapped Plugin API changelog, documents its use for minimum IDE version selection, and updates compatibility documentation to reflect ABI validation enforced since 26.28.

Changes

Plugin API documentation

Layer / File(s)	Summary
Versioned API changelog docs/PLUGIN_API_CHANGELOG.md	Defines YY.WW version semantics, records historical additive API capabilities, explains caveats, and documents regeneration commands.
Authoring and compatibility references docs/PLUGIN_AUTHORING.md, docs/plugin-api.md	Links minimum IDE version selection to the changelog and documents checked-in ABI validation for :plugin-api.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Poem

A rabbit hops through versions bright,
Mapping API trails by moonlit light.
“Set your minimum,” the bunny sings,
While ABI checks guard plugin things.
Newest first—what tidy wings!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding a Plugin API changelog with YY.WW capability history.
Description check	✅ Passed	The description accurately matches the documentation-only Plugin API changelog and related doc updates.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ADFA-1713-plugin-api-changelog

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/PLUGIN_API_CHANGELOG.md`:
- Around line 150-164: Update the “Regenerating this doc” guidance to qualify
the ABI dump as the source of truth only for ABI symbols, then add a separate
source-history/audit step covering non-ABI contracts in docs/plugin-api.md,
including manifest keys, permission strings, and package/format requirements.
Ensure the guidance accounts for additions such as plugin.icon_day and
ide.environment.write when determining the appropriate plugin.min_ide_version.
- Around line 13-25: Define one consistent plugin-version contract across both
documentation sites: clarify in docs/PLUGIN_API_CHANGELOG.md lines 13-25 whether
versions are strict ISO YY.WW values or release tags, then align the dated
entries, 26.02 exception, and 99.0.0 example with that contract; update
docs/PLUGIN_AUTHORING.md lines 78-80 to use the same values or explicitly label
1.0.0 examples as legacy loader fallbacks.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7b219d39-a1e6-41db-b383-6d181156ef62

📥 Commits

Reviewing files that changed from the base of the PR and between 44bf899 and 0ba6cee.

📒 Files selected for processing (3)

• docs/PLUGIN_API_CHANGELOG.md
• docs/PLUGIN_AUTHORING.md
• docs/plugin-api.md