This is an automated email from the ASF dual-hosted git repository.
epugh pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/solr-mcp.git
The following commit(s) were added to refs/heads/main by this push:
new 5a522fce docs(changelog): write the 1.0.0 release notes and fix the
release steps (#254)
5a522fce is described below
commit 5a522fcecf6bafee4ad8708d701693622af70294
Author: Aditya Parikh <[email protected]>
AuthorDate: Mon Oct 26 15:03:47 2026 -0400
docs(changelog): write the 1.0.0 release notes and fix the release steps
(#254)
* docs(changelog): write the 1.0.0 release notes and fix the release steps
Fill [Unreleased] with a summary and one Added entry per user-facing
capability for the first release.
Document the plugin's summary as the place for release highlights, and
fix the release steps: patchChangelog names the section after
project.version, which the build script assigns, so -Pversion=1.0.0
produced a 1.0.0-SNAPSHOT heading. The cut now runs in the release
preparation commit after the version bump. Set versionPrefix so the
generated links point at the releases/solr-mcp/<version> tags instead
of nonexistent v<version> tags.
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
Signed-off-by: Aditya Parikh <[email protected]>
* docs(changelog): state Solr 9.4 through 10 as the supported range
Solr 8.x is end-of-life upstream and was dropped from the tested range
in #255, so the 1.0.0 summary no longer claims 8.11.
Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
Signed-off-by: Aditya Parikh <[email protected]>
---------
Signed-off-by: Aditya Parikh <[email protected]>
Co-authored-by: Claude Opus 5.5 (1M context) <[email protected]>
---
CHANGELOG.md | 14 ++++++++
build.gradle.kts | 7 ++--
dev-docs/CHANGELOG_GUIDE.md | 83 ++++++++++++++++++++++++++-------------------
dev-docs/release-process.md | 14 ++++----
4 files changed, 76 insertions(+), 42 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index ef94dc1b..d8c00aa3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,8 +2,22 @@
## [Unreleased]
+Apache Solr MCP 1.0.0 is the project's first release: a Model Context Protocol
(MCP) server that lets AI assistants search, index and manage Apache Solr. It
runs over STDIO for desktop and IDE clients, or over HTTP for remote use with
OAuth2 authentication on by default. It is built on Spring Boot 4.1 and Spring
AI 2.0, works with Solr 9.4 through 10, and ships as a JAR (Java 25), a
multi-architecture JVM Docker image and GraalVM native images.
+
### Added
+- **Search**: the `search` tool runs full-text queries with filter queries,
faceting, sorting and pagination.
+- **Indexing in four formats**: `index-json-documents`, `index-csv-documents`,
`index-xml-documents` (Solr update XML; only `<add>` is accepted, so the tool
cannot delete documents or issue commits) and `index-markdown-documents`, which
extracts front matter, title, headings and body text from each document.
+- **Collection management**: `list-collections`, `create-collection`,
`check-health` and `get-collection-stats`, plus alias management with
`list-aliases`, `create-alias` and `delete-alias`.
+- **Schema inspection and additive changes**: `get-schema`, `add-fields` and
`add-field-types`. The schema tools only add; they never change or remove
existing fields or field types.
+- **Prompts, resources and completions**: guided prompts
(`explore-collections`, `setup-collection`, `search-collection`, `index-data`,
`view-schema`, `design-schema`), the `solr://collections` and
`solr://{collection}/schema` resources, and collection-name completion for
their arguments.
+- **STDIO and HTTP transports**: STDIO is the default; `PROFILES=http` serves
stateless streamable HTTP.
+- **OAuth2 security for HTTP, on by default**: JWT bearer tokens from the
issuer in `OAUTH2_ISSUER_URI`, with audience validation and configurable CORS
origins (`MCP_CORS_ALLOWED_ORIGINS`). Setup guides cover Auth0 and Keycloak.
+- **Docker images**: `apache/solr-mcp`, a JVM image (amd64 and arm64) that
serves both transports, and GraalVM native images for each transport
(`<version>-native-stdio`, `<version>-native-http`) on GHCR.
+- **Observability in HTTP mode**: OpenTelemetry traces, metrics and logs
exported over OTLP/HTTP, with a span for every tool call and logs correlated to
the trace they were written in.
+- **Software bill of materials and license disclosure**: a CycloneDX SBOM
embedded in the JAR and every image and served at `/actuator/sbom/application`
in HTTP mode, and a binary `LICENSE`/`NOTICE` that lists every bundled
dependency.
+- **Client setup guides** for Claude Desktop, Claude Code, Codex, ChatGPT, VS
Code, Cursor, JetBrains, Zed and MCP Inspector.
+
### Changed
### Fixed
diff --git a/build.gradle.kts b/build.gradle.kts
index cb451c40..4bc5d7c9 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -422,10 +422,13 @@ spotless {
// Gradle's own `project.version` (e.g. "1.0.0-SNAPSHOT") and fails with
MissingVersionException
// if neither is given.
//
-// See the release process doc (apache/solr-mcp#157; will land as
dev-docs/release-process.md)
-// for where this fits in an ASF release.
+// patchChangelog names the new section after `project.version`, so run it
after the release
+// commit sets `version` above; `-Pversion=` does not work because this script
assigns `version`.
+// versionPrefix matches the release tags (releases/solr-mcp/<x>) so the
generated compare and
+// commits links resolve. See dev-docs/CHANGELOG_GUIDE.md and
dev-docs/release-process.md.
changelog {
repositoryUrl = "https://github.com/apache/solr-mcp";
+ versionPrefix = "releases/solr-mcp/"
groups = listOf("Added", "Changed", "Fixed", "Security")
}
diff --git a/dev-docs/CHANGELOG_GUIDE.md b/dev-docs/CHANGELOG_GUIDE.md
index 56786fd6..38746b67 100644
--- a/dev-docs/CHANGELOG_GUIDE.md
+++ b/dev-docs/CHANGELOG_GUIDE.md
@@ -35,55 +35,70 @@ in place rather than deleting them.
Write the entry as the *effect*, not the commit — no commit hashes, PR
numbers, or scope
prefixes; that's what `git log` and `gh pr view` are for.
+## Release highlights (the summary)
+
+Plain paragraphs placed between a version heading and its first `###` group
are that version's
+**summary**. Use it for the two or three sentences a reader needs before the
item list: what the
+release is about and its headline changes. `patchChangelog` carries the
summary into the released
+section, and `getChangelog` prints it at the top of the extracted notes.
+
+```markdown
+## [Unreleased]
+
+Solr MCP 1.1 adds semantic search and ...
+
+### Added
+```
+
+Keep the summary to prose. Bullets above the first `###` are not part of the
summary (the plugin
+treats them as items with no group, and `--no-summary` leaves them in), and a
`### Highlights`
+heading would be parsed as one more group. Detail belongs in the groups below;
the summary
+should not repeat them. Releases with nothing to headline can omit it.
+
## At release time
1. **Review `[Unreleased]`** for completeness against everything that actually
shipped since the
last release (`git log <last-tag>..HEAD --no-merges` is the check, not the
source of the
- entries — entries should already be there from step "day to day" above).
-2. **Cut the version.** The plugin's `changelog { version = project.version }`
default will
- pick up whatever `version` is set to in `build.gradle.kts` — but during
development that's a
- `-SNAPSHOT` value, which is *not* what you want in the changelog heading.
Override it
- explicitly for the release:
+ entries — entries should already be there from step "day to day" above),
and write or update
+ the summary.
+2. **Cut the version** in the release-preparation commit
+ ([release process](release-process.md), step 1), after `version` in
`build.gradle.kts` has
+ been changed from the `-SNAPSHOT` value to the release version:
```bash
- ./gradlew patchChangelog -Pversion=1.0.0
+ ./gradlew patchChangelog --console=plain -q
```
- This renames `[Unreleased]` to `## [1.0.0] - <today>` and opens a fresh,
empty
- `[Unreleased]` section above it.
-3. **Extract the release notes** for reuse as the GitHub Release body /
release announcement:
+ This renames `[Unreleased]` to `## [<version>] - <today>`, keeps the
summary, drops groups that
+ have no entries, adds the compare/commits links for the
`releases/solr-mcp/<version>` tag (the
+ plugin's `versionPrefix`), and opens a fresh, empty `[Unreleased]` section
above it.
+ The section is named after `project.version`; passing `-Pversion=...`
instead of editing
+ `build.gradle.kts` has no effect, because the build script assigns
`version` itself.
+3. **Commit `CHANGELOG.md`** with the version change, before tagging the
release candidate: it
+ is source, so it must be in the voted source archive.
+4. **Extract the release notes** for the vote email, the GitHub Release body
and the
+ announcement:
```bash
./gradlew getChangelog --console=plain -q --no-header
--project-version=1.0.0
```
-4. **Commit `CHANGELOG.md`** as part of the release branch (see the release
process doc,
- [apache/solr-mcp#157](https://github.com/apache/solr-mcp/pull/157) — will
land as
- `dev-docs/release-process.md` — for where this fits relative to building
and signing
- artifacts; do it before signing, since it's source, not a build output).
+ The output starts with the summary and lists only the groups that have
entries.
Useful read-only commands while iterating:
```bash
-# Preview what would ship, without mutating the file
-./gradlew getChangelog --console=plain -q --unreleased --no-summary
--no-empty-sections
+# Preview what would ship, summary included, without mutating the file
+./gradlew getChangelog --console=plain -q --unreleased --no-empty-sections
# Scaffold a fresh CHANGELOG.md from nothing (already done for this repo; here
for reference)
./gradlew initializeChangelog
```
-## Handling the first release (1.0.0)
-
-This is the first release this project has ever cut, so `[Unreleased]` was
seeded empty rather
-than back-filled — entries only exist from the point this guide was adopted
onward. Whoever
-prepares the 1.0.0 release notes needs a one-time, deliberate pass over the
*entire* project
-history before running `patchChangelog`, not just the recent PRs:
-
-1. Get the full commit range: `git log --no-merges
--format='%x1e%H%x1f%s%x1f%b' HEAD` from the
- project's first commit (there are no prior tags to diff against).
-2. Categorize into `Added` / `Changed` / `Fixed` / `Security`, collapsing
multiple commits that
- implement one user-facing capability into a single entry (e.g. the several
PRs behind
- markdown indexing become one `Added` line, not five). Drop internal-only
commits.
-3. Write the result into `[Unreleased]` by hand, then follow **At release
time** above.
-
-Doing this well is a real editing pass, not a mechanical `git log` dump —
budget time for it
-alongside the other 1.0.0 release-process work, and do it close to the actual
release so the
-notes reflect what's really shipping (see `dev-docs/release-process.md` and
the tracking issues
-for the open blockers on that release). Every release after 1.0.0 skips this
step entirely,
-since `[Unreleased]` will already be current.
+## The first release (1.0.0)
+
+1.0.0 has no earlier release to diff against, so its `[Unreleased]` section
was written by hand
+from the project's whole history rather than accumulated PR by PR: a summary
plus one `Added`
+entry per user-facing capability (several PRs behind one capability, such as
Markdown indexing,
+are one entry). `Changed`, `Fixed` and `Security` are empty because they
describe differences
+from a previous release; `patchChangelog` drops them from the 1.0.0 section.
+
+Before cutting 1.0.0, check the section against what is actually shipping —
the tool list in the
+source, the published images and the documentation — and add any capability
merged after it was
+written. From 1.0.1 on, `[Unreleased]` is kept current by the PRs themselves.
diff --git a/dev-docs/release-process.md b/dev-docs/release-process.md
index d86544c7..69b4b75c 100644
--- a/dev-docs/release-process.md
+++ b/dev-docs/release-process.md
@@ -47,18 +47,20 @@ changes intended for this release.
Set the exact release version in `build.gradle.kts`.
-Prepare a short change summary for the vote. A separate release-notes file in
-the source archive is optional; GitHub Release notes can be published after
-the vote. To update version labels on Linux, run these commands from the
-repository root, then review and publish the branch:
+Promote the `[Unreleased]` section of `CHANGELOG.md` to the release version in
+the same commit. The promoted section is the change summary for the vote and
+the GitHub Release body (see [Changelog Guide](CHANGELOG_GUIDE.md)). To update
version
+labels and the changelog on Linux, run these commands from the repository root,
+then review and publish the branch:
```bash
sed -i 's/version = "1\.0\.0-SNAPSHOT"/version = "1.0.0"/' build.gradle.kts
+./gradlew patchChangelog --console=plain -q
rg -l -0 '1\.0\.0-SNAPSHOT' README.md dev-docs -g '*.md' -g
'!release-process.md' \
| xargs -0 -r sed -i 's/1\.0\.0-SNAPSHOT/1.0.0/g'
git diff --check
-git diff -- build.gradle.kts README.md dev-docs
-git add build.gradle.kts README.md dev-docs
+git diff -- build.gradle.kts CHANGELOG.md README.md dev-docs
+git add build.gradle.kts CHANGELOG.md README.md dev-docs
git commit -m "chore(release): prepare 1.0.0"
git status --short # expected: no output
git push -u origin branch_1_0_0
