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 13b17431 build(release): wire org.jetbrains.changelog and populate
CHANGELOG.md (#221)
13b17431 is described below
commit 13b17431557e22d5a7ddf04e6ea6463e2df0d4a9
Author: Aditya Parikh <[email protected]>
AuthorDate: Tue Oct 6 14:36:20 2026 -0400
build(release): wire org.jetbrains.changelog and populate CHANGELOG.md
(#221)
* build(release): wire org.jetbrains.changelog and populate CHANGELOG.md
Adds the org.jetbrains.changelog Gradle plugin (2.5.0) and a Keep a
Changelog-format CHANGELOG.md with an [Unreleased] section reflecting
recent JSON/CSV/XML indexing and native-logging fixes.
Entries are maintained by hand as PRs land; patchChangelog promotes
[Unreleased] into a versioned section at release time, and getChangelog
extracts one version's notes for reuse (e.g. as a release announcement
body). This mirrors the manual-entry direction the maintainers already
settled on after closing PR #34 (release-please) and PR #35
(git-semver-plugin), which proposed fully commit-driven automation.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Signed-off-by: Aditya Parikh <[email protected]>
(cherry picked from commit 68168aecee3c47924dc5d488edfd222437c1c998)
* docs(release): add changelog guide, seed CHANGELOG.md empty for 1.0.0
Document how contributors add entries to CHANGELOG.md's [Unreleased]
section day-to-day, and the exact patchChangelog/getChangelog commands
to run at release time, in dev-docs/CHANGELOG_GUIDE.md. Link it from
the README docs index.
Since this is the project's first release, [Unreleased] is seeded
empty rather than back-filled with a few example entries -- the guide
calls out that the actual 1.0.0 notes need a deliberate one-time pass
over the full commit history, done close to the real release so they
reflect what's shipping.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Signed-off-by: Aditya Parikh <[email protected]>
* fix(release): correct getChangelog usage docs, link PR #157 not a phantom
path
The build.gradle.kts comment claimed getChangelog falls back to
project.version without --project-version; verified against the
running plugin that it instead throws MissingVersionException, and
that --unreleased works standalone (no --project-version needed).
Also point CHANGELOG_GUIDE.md at apache/solr-mcp#157 instead of
dev-docs/release-process.md, which doesn't exist on main yet.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Signed-off-by: Aditya Parikh <[email protected]>
---------
Signed-off-by: Aditya Parikh <[email protected]>
Co-authored-by: Claude Sonnet 5 <[email protected]>
---
CHANGELOG.md | 13 +++++++
README.md | 2 +-
build.gradle.kts | 23 ++++++++++++
dev-docs/CHANGELOG_GUIDE.md | 89 +++++++++++++++++++++++++++++++++++++++++++++
gradle/libs.versions.toml | 2 +
5 files changed, 128 insertions(+), 1 deletion(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..ef94dc1b
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,13 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+### Security
+
+[Unreleased]: https://github.com/apache/solr-mcp/commits
diff --git a/README.md b/README.md
index 4521e02e..f34140bc 100644
--- a/README.md
+++ b/README.md
@@ -166,7 +166,7 @@ Running in **HTTP mode** — OAuth2, CORS, and the
`HTTP_SECURITY_ENABLED` toggl
**Developing it**
- [Development guide](dev-docs/DEVELOPMENT.md) — build, run, test, IDE, native
image, SBOM · [Architecture](dev-docs/ARCHITECTURE.md)
- [Deployment](dev-docs/DEPLOYMENT.md) — Docker images, the three-image
matrix, registries, Kubernetes · [Troubleshooting](dev-docs/TROUBLESHOOTING.md)
-- [GraalVM native image spec](dev-docs/graalvm-native-image.md) ·
[Contributing](CONTRIBUTING.md)
+- [GraalVM native image spec](dev-docs/graalvm-native-image.md) · [Changelog
guide](dev-docs/CHANGELOG_GUIDE.md) · [Contributing](CONTRIBUTING.md)
> **Container images:** published images are not yet available on a public
> registry. The Docker examples in the client guides use a **locally built**
> image — build it with `./gradlew jibDockerBuild` (produces
> `solr-mcp:latest`). See [Building Docker
> images](dev-docs/DEPLOYMENT.md#docker-images-with-jib).
diff --git a/build.gradle.kts b/build.gradle.kts
index b0933b5e..e1d7692d 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -28,6 +28,7 @@ plugins {
alias(libs.plugins.jib)
alias(libs.plugins.graalvm.native) apply false
alias(libs.plugins.cyclonedx)
+ alias(libs.plugins.changelog)
// Generates ASF source/binary LICENSE + NOTICE (buildSrc convention
plugin).
// Listed after spring-boot + cyclonedx so productionRuntimeClasspath and
// cyclonedxBom exist when it wires its tasks. See buildSrc/.
@@ -341,6 +342,28 @@ spotless {
}
}
+// Release Notes / CHANGELOG.md (org.jetbrains.changelog)
+// ========================================================
+// Maintains CHANGELOG.md in Keep a Changelog format. Entries are added by
hand to the
+// [Unreleased] section as PRs land (see CONTRIBUTING guidance); at release
time
+// `patchChangelog` promotes [Unreleased] into a versioned section, and
`getChangelog`
+// extracts one version's notes for reuse (e.g. as a GitHub Release body).
+//
+// ./gradlew patchChangelog # cut
[Unreleased] -> version section
+// ./gradlew getChangelog --console=plain -q --no-header --unreleased
# unreleased notes
+// ./gradlew getChangelog --console=plain -q --no-header
--project-version=1.0.0 # one version's notes
+//
+// getChangelog requires either --unreleased or --project-version=<x>: it does
not fall back to
+// 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.
+changelog {
+ repositoryUrl = "https://github.com/apache/solr-mcp";
+ groups = listOf("Added", "Changed", "Fixed", "Security")
+}
+
// Docker Integration Test Task
// =============================
// Runs integration tests against the appropriate Docker image:
diff --git a/dev-docs/CHANGELOG_GUIDE.md b/dev-docs/CHANGELOG_GUIDE.md
new file mode 100644
index 00000000..56786fd6
--- /dev/null
+++ b/dev-docs/CHANGELOG_GUIDE.md
@@ -0,0 +1,89 @@
+# Changelog Guide
+
+`CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com) and is
managed by the
+`org.jetbrains.changelog` Gradle plugin (`build.gradle.kts`). It has one job:
give every release
+a real, human-readable set of release notes without anyone reverse-engineering
them from commit
+history at the last minute.
+
+## Day to day: add an entry with your PR
+
+If your change is user-visible — a new tool, a changed response shape, a fixed
bug, a closed
+security gap — add one line to the `[Unreleased]` section of `CHANGELOG.md` in
the same PR,
+under the group that fits:
+
+```markdown
+## [Unreleased]
+
+### Added
+
+- **index-json-documents** now accepts a typed array of documents in one call.
+
+### Changed
+
+### Fixed
+
+- Configuring `solr.url` to an address SolrJ cannot reach now fails fast at
startup.
+
+### Security
+```
+
+Skip the entry for internal-only changes: refactors, test additions, CI/build
tweaks, docs,
+dependency bumps with no observable effect. If a group ends up with no entries
at release time,
+it's simply omitted from the extracted notes (see `getChangelog` below) —
leave empty headers
+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.
+
+## 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:
+ ```bash
+ ./gradlew patchChangelog -Pversion=1.0.0
+ ```
+ 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:
+ ```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).
+
+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
+
+# 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.
diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml
index b5cdc021..73db0b55 100644
--- a/gradle/libs.versions.toml
+++ b/gradle/libs.versions.toml
@@ -23,6 +23,7 @@ jib = "3.5.3"
spotless = "7.0.2"
graalvm-native = "0.10.6"
cyclonedx-plugin = "2.4.1"
+changelog-plugin = "2.5.0"
# Main dependencies
spring-ai = "1.1.7"
@@ -140,3 +141,4 @@ jib = { id = "com.google.cloud.tools.jib", version.ref =
"jib" }
spotless = { id = "com.diffplug.spotless", version.ref = "spotless" }
graalvm-native = { id = "org.graalvm.buildtools.native", version.ref =
"graalvm-native" }
cyclonedx = { id = "org.cyclonedx.bom", version.ref = "cyclonedx-plugin" }
+changelog = { id = "org.jetbrains.changelog", version.ref = "changelog-plugin"
}
