[janhoy]

Closes #866

Adopting a new Solr release means editing 15 files that each carry the version — 14 repeating the full string, plus .github/workflows/e2e-tests.yaml which pins the major alone — and no make target checks that they agree, so a partial bump passes CI. The compatibility matrix and both charts' artifacthub.io/changes changelogs are hand-maintained, and are the steps most often skipped. This writes that procedure down.

What it covers

• The version sites as a table, including the traps: the e2e workflow pins solr:9 so a git grep of the previous version cannot see it, and appVersion means the Solr version in helm/solr but the operator version in helm/solr-operator, which must never be touched here.
• Where to read what a release changed: the ref guide's major-changes-in-solr-<major>.adoc first, then CHANGELOG.md, then the security atom feed for CVEs — and across the whole span crossed, since adopting 9.11.0 off a 9.10.0 default means reading 9.10.1 too.
• Which operator code a release can move — admin APIs, probes, security.json, TLS, rolling updates, scaling — each with its file.
• Sizing from XS to XL with an explicit cut line: attempt XS/S/M, stop at L. A minor release with an L item still takes the version bump and files issues for the rest; a major with one halts instead, because a half-gated major leaves the operator claiming support it does not have.
• A separate path for a new Solr major, where behaviour is gated on the major rather than carried by a version string, and where supporting a major and defaulting to it are two decisions and two PRs.
• The matrix, the both-charts changelog, and that the two charts' containsSecurityUpdates annotations are independent of each other.

Where it lives

.agents/skills/, the convention #864 establishes — the vendor-neutral location most assistants read, with a pointer from AGENTS.md. Markdown only, no scripts, so a human can follow the same checklist by hand.

This must be merged after #864. As the branch stands it duplicates that PR's .gitignore entry and its entire ## Skills section in AGENTS.md, so the two will conflict. Once #864 is in I will rebase and cut this down to what it should actually be: the new SKILL.md, plus one row added to the table #864 created.

Tried before proposing

Ran it end to end to adopt Solr 9.11.0 (#869). It found the full set of version sites, correctly concluded the release needs no operator work, determined the matrix needed no new column, and produced both charts' changelog entries. make e2e-tests could not run locally because of #859, and the skill's rules made the PR say so plainly rather than quietly skip it.

Two things it got wrong on that run, both fixed here: it read only the target release and so missed that the CVE fixes are in the intervening 9.10.1, and it implied a security entry on one chart carries over to the other.

Note on the major-version section

"A new Solr major version" describes the mechanism from #827 — SolrCloud.SolrMajorVersion() parsed from the image tag, and an UnsupportedSolrVersion warning event for a major the operator does not support. #827 is still open, so that section documents something not yet on main. The skill says so in-line and tells the reader to re-read the code first, but if you would rather main not describe an unmerged PR, that section can wait for #827 or move to a follow-up.

---

🤖 AI assisted PR, approved by me

[Copilot]

🟡 Changes recommended

The procedure can test the wrong Solr version and generate inaccurate upgrade notices, so its operational guidance needs correction before use.

4 open issues

• Preserve older initial version for upgrade demonstration · New
• Parse action arguments before running getopts · New
• Operator upgrades do not update existing SolrCloud images · New
• Pre-commit clean-status check conflicts with staged changes · New

What changed in this PR

Adds a Markdown-only agent skill for adopting Solr releases, documenting the operator’s version updates, compatibility checks, and release notes.

Changes:

• Defines release validation, operator-impact sizing, testing, and separate handling for new major versions.
• Records version sites, compatibility-matrix maintenance, and both charts’ changelog requirements.
• Adds skill discovery guidance and ignores local Claude configuration, overlapping with prerequisite PR #864.

File	Description
AGENTS.md	Introduces skill discovery guidance and lists solr-version-support.
.gitignore	Excludes local .claude/ configuration.
.agents/​skills/​solr-version-support/​SKILL.md	Documents the Solr release-adoption procedure and verification checklist.

_{Review effort: Balanced}