Release Process

[epugh]

Document the steps for cutting a release. Maybe someday this will be scripted!

[epugh]

@adityamparikh @janhoy I am writing out the steps... Hopefully our third attempt will work.

[epugh]

I am pulling in some of the steps from #158, but I want to keep it very short..... So probably will just have a few examples.

[epugh]

Okay, one more pass through on the steps.

[janhoy]

This looks like a preliminary draft checklist, not a full, detailed release process document that any new RM could be expected to be able to follow. But perhaps that was not the intentino?

I'd prefer some more writing out example commands to run, expected results, a bit more verification, more about ATR in general (what it does and does not do), and the vote itself, steps for uploading voted upon artifacts to downloads.apache.org/solr/ (versioned sub folders under /solr/mcp ?), something about announcing the release, perhaps adding release notes to github "release" and publishing the official new docker image somewhere? Publishing updated documentation (done automatically?) etc.

[epugh]

This looks like a preliminary draft checklist, not a full, detailed release process document that any new RM could be expected to be able to follow. But perhaps that was not the intentino?

I'd prefer some more writing out example commands to run, expected results, a bit more verification, more about ATR in general (what it does and does not do), and the vote itself, steps for uploading voted upon artifacts to downloads.apache.org/solr/ (versioned sub folders under /solr/mcp ?), something about announcing the release, perhaps adding release notes to github "release" and publishing the official new docker image somewhere? Publishing updated documentation (done automatically?) etc.

Yeah, this was definitly just the draft checklist. One thing I am struggling a bit is that I've never been a RM for Solr, which means I don't have the same perspective of what a release process should look like. I ALSO don't have any clue on the whole Docker release process, and was planning on punting that for a post 1.0 task. Having said that, I know @adityamparikh would prefer that we had a Docker image as part of our 1.0 release.

So all of that is me saying, I'd LOVE your efforts on the release process. I'd love to see what a buffed up release porcess would look like, and happy to help test etc.

[adityamparikh]

@janhoy Will you able to help us figure out the release process the right Apache way with Apache Trusted Releases?
To get 1.0 out we proposed making the jar available.
Ideally I'd like to publish Docker image that non-JVM folks can download from a registry and spin it up. We already have the plumbing for building and publishing docker images.

[janhoy]

We could keep it minimal in v1.0 release, and define a release as the src.tgz and binary.jar with shasum and asc signatures, and these are uploaded to https://downloads.apache.org/solr/mcp/1.0.0/ and then the MCP web site download page gets updated with correct links to those downloads. We don't need to supply official docker images for v1.0.0 at all.

@epugh Try to feed all the info in this PR to an LLM to draft a more polished release-process document. Ask it to respect the official ASF release policy and structure the doc in such a way that any committer familiar with the code base can act as RM. I guess that document will be very close to what we need, and we can then review it manually?

[epugh]

@epugh Try to feed all the info in this PR to an LLM to draft a more polished release-process document. Ask it to respect the official ASF release policy and structure the doc in such a way that any committer familiar with the code base can act as RM. I guess that document will be very close to what we need, and we can then review it manually?

I am going to do this tomorrow, but I'll be honest, I don't feel very confident of being able to know if something is good or not. Heck, I tried twice to ship this thing thinkign the process as I knew it was good enough.. But maybe LLM will do better!

[adityamparikh]

@epugh — I checked every concrete command in this against the repo as it stands on main (a84033b), so you can iterate on the prose without re-verifying the mechanics. Most of it holds up; there are two gaps that I think are the ones @janhoy's review is actually pointing at.

Verified correct

• dev-docs/SMOKE_TEST.md exists at exactly that path (landed in docs: add tester quick-start smoke test guide #158). ✅
• The RAT check really is wired into check, and the plugin id is spelled correctly — buildSrc/src/main/kotlin/org.apache.solr.mcp.rat.gradle.kts. So "./gradlew build already ran it" is accurate, not aspirational. ✅
• The unzip -p build/libs/solr-mcp-X.Y.Z.jar META-INF/LICENSE spot-check works — those files really are generated into the bootJar by generateBinaryLicense/generateBinaryNotice. ✅
• Tag name releases/solr-mcp/1.0.0 matches the protected_tags: ["releases/*"] rule in .asf.yaml, so it will be protected on creation. ✅

Gap 1 — nothing here produces a source release

This is the big one. @janhoy's definition upthread was:

define a release as the src.tgz and binary.jar with shasum and asc signatures

./gradlew clean build produces no src.tgz. I checked build.gradle.kts for any Tar/distTar/source-archive task and there is none. So an RM following these steps literally would upload a binary-only release, which is the one thing ASF policy does not allow — the source release is the formal artifact being voted on.

Either a source-archive task needs adding to the build, or the doc needs an explicit manual step (e.g. git archive --format=tar.gz --prefix=solr-mcp-1.0.0/ releases/solr-mcp/1.0.0 -o solr-mcp-1.0.0-src.tgz).

Gap 2 — for fn in *.jar signs four jars, not one

build.gradle.kts calls both withSourcesJar() and withJavadocJar() alongside the bootJar and the plain jar, so after clean build the build/libs/ directory holds roughly:

solr-mcp-1.0.0.jar           <- bootJar (the fat/binary artifact)
solr-mcp-1.0.0-plain.jar     <- thin jar
solr-mcp-1.0.0-sources.jar
solr-mcp-1.0.0-javadoc.jar

The signing and sha512 loops both glob *.jar, so they sign and checksum all four. Worth stating which of these are actually part of the release and being uploaded to ATR — an RM has no way to infer that "binary.jar" means the bootJar and not -plain.jar.

Also: the loops imply the working directory is build/libs (the ../../gpgsign.sh relative path only resolves from there), but that is never stated. And gpgsign.sh is not in this repo — worth saying where it comes from, since a first-time RM cannot find it.

Smaller notes

• sha512 is not present on a stock macOS install (shasum -a 512 is). My machine happens to have /sbin/sha512, so I could not reproduce the failure, but shasum -a 512 "$fn" > "$fn.sha512" is the spelling that works unmodified on both macOS and Linux and would let you drop the "use sha512sum on Linux" caveat.
• Step 3 points at PR chore(release): cut 1.0.0 #136 for the -SNAPSHOT removal. Note chore(release): cut 1.0.0 #136 currently targets main, not a release branch — consistent with your comment there that it should go against branch_1_0_0. Might be worth stating in this doc that it gets retargeted, so the two documents do not disagree.

Happy to send a PR against your branch with the source-archive step and the signing-scope clarification if that is useful, rather than you folding it in by hand — just say the word.

[adityamparikh]

@epugh — following up on my review with a concrete PR rather than more prose: epugh/solr-mcp#1 against add_release_steps.

It is deliberately three small edits, not a rewrite, since you said you want to keep this short:

1. Adds the source-release step. ./gradlew clean build emits jars only — there is no source-archive task in build.gradle.kts — so the steps as written would produce a binary-only release. Added an explicit git archive from the commit being voted on; I ran it and it yields a 203-entry tarball of tracked files only.
2. Scopes the signing/checksum loops. withSourcesJar() + withJavadocJar() mean build/libs holds four jars, so for fn in *.jar signs all of them. Now copies the two released artifacts to build/release and works there — which also pins down the working directory the ../../gpgsign.sh path was silently assuming.
3. sha512 → shasum -a 512, which exists on both macOS and Linux, so the per-OS caveat goes away. Verified with shasum -a 512 -c.

I deliberately left the vote mechanics, ATR background and verification steps that @janhoy asked for alone — those are policy and yours to write. This only covers the mechanical parts I could check against the repo.

Also worth noting for sequencing: I've opened #181 with a verified merge order for the rebased PR queue, and it flags that #136 is the -SNAPSHOT step referenced here and needs retargeting to branch_1_0_0 as you called out.