ci(scripts): Add coordinated release orchestrator and runbook

[jeffjensen]

What

Adds the coordinated release tooling for the database-audits modules to the parent repo.

• release-all.ps1 — orchestrates the parent -> core -> spring-boot release in dependency order: prompts for each module's release/next-development versions, runs pre-flight, adopts each freshly released upstream as a build(pom) bump, runs release:prepare, and waits for the artifact on Maven Central before releasing the dependent module. Subset-capable (-Modules), resumable, and has a -DryRun rehearsal.
• README.adoc — orientation: module layout, dependency order, and how cross-references are pinned.
• RELEASING.adoc — the release procedure: one-command path, manual fallback, rollback, and post-release verification.

Pre-flight behavior

The pre-flight confirms each repo is releasable rather than imposing rigid requirements:

• No uncommitted tracked changes — untracked/loose files are ignored.
• The current branch is level with its origin counterpart — the branch need not be main, but whatever you release from must already be pushed.
• Docker is running (required by core/spring-boot integration tests during release:prepare).

The signed deploy stays with each repo's tag-triggered release.yml; this orchestrates only the local release:prepare side.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UitsP43vNdmvr9HVHaToTq

Summary by CodeRabbit

• New Features

  • Added a one-command, guided multi-repository release workflow via release-all.ps1, supporting dry runs, interactive confirmation, resumable releases, and selective module execution in dependency order.
  • Added automated pre-flight validation and downstream release gating by waiting for artifacts to appear on Maven Central before proceeding.

• Documentation

  • Added README.adoc describing the shared Maven parent layout, version line conventions, and required release sequencing.
  • Added RELEASING.adoc with end-to-end release instructions, rollback/abort guidance, and post-release verification.

[coderabbitai]

Warning

Review limit reached

@jeffjensen, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 39 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 66bdb6d5-6e96-4265-932f-0703410887b8

📥 Commits

Reviewing files that changed from the base of the PR and between fa099c9 and 6963821.

📒 Files selected for processing (4)

• README.adoc
• RELEASING.adoc
• pom.xml
• release-all.ps1

📝 Walkthrough

Walkthrough

Adds release-all.ps1, a PowerShell orchestrator that releases the parent, core, and spring-boot repositories in dependency order, plus README.adoc and RELEASING.adoc documentation covering the layout, release procedure, fallback paths, rollback, and verification.

Changes

Multi-repo Release Orchestration

Layer / File(s)	Summary
README and RELEASING documentation README.adoc, RELEASING.adoc	README.adoc describes the module layout, dependency/release order, and links to RELEASING.adoc. RELEASING.adoc covers the release mechanism, preconditions, one-command path via release-all.ps1, manual fallback command sequences, rollback instructions, and post-release verification.
Script parameters, config, and utility helpers release-all.ps1	Defines the script entry point with $Modules, -DryRun, and -Yes parameters, strict mode, release configuration, console output helpers, Maven wrapper execution, project.version extraction, and the spring-boot property reader.
Version prompting, environment guards, and Maven Central polling release-all.ps1	Implements interactive version prompting and validation, repository and branch checks, Docker availability checks, and Maven Central artifact polling.
Adopt mechanics, pre-flight, release plan, and main release loop release-all.ps1	Implements upstream adoption and commit handling, downstream dependency checks, pre-flight validation, release plan construction, the per-module release loop, and completion output.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding coordinated release tooling and its runbook/docs.
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 ci/release-orchestration

---

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.}

[qodo-code-review]

PR Summary by Qodo

Add coordinated multi-repo release orchestrator and release runbook

✨ Enhancement 📝 Documentation 🕐 40+ Minutes

AI Description

• Add PowerShell orchestrator to release parent/core/spring-boot in dependency order
• Validate repos are releasable, then run Maven release:prepare and wait for Central availability
• Document repo layout, cross-reference pinning, and end-to-end/manual release procedures

Diagram

graph TD
  U["Release engineer"] --> S["release-all.ps1"] --> G{"Pre-flight checks"} --> R1["parent repo"] --> M1["mvnw release:prepare"] --> T1["Push tag vX.Y.Z"] --> CI["GitHub Actions release.yml"]
  CI --> C[("Maven Central")]
  S --> W["Wait for Central artifact"] --> R2["core/spring-boot repo"]

  subgraph Legend
    direction LR
    _usr["User"] ~~~ _scr["Script"] ~~~ _dec{"Decision"} ~~~ _repo["Repo"] ~~~ _db[("Registry")]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Move orchestration into GitHub Actions (workflow_dispatch)

• ➕ No local environment dependencies (PowerShell, Docker running locally, Maven wrapper execution)
• ➕ Centralizes logs/audit trail and reduces operator variance
• ➕ Easier to enforce consistent prerequisites and permissions
• ➖ Harder to interactively prompt for versions and handle partial resumes cleanly
• ➖ Would require CI access to multiple repos and coordinated checkouts/credentials
• ➖ Long-running Central polling can consume CI minutes and complicate retries

2. Use a single multi-module Maven reactor build (merge repos)

• ➕ Maven naturally enforces build/release ordering and shared version alignment
• ➕ Eliminates cross-repo version adoption commits and Central polling gates
• ➖ Large organizational change: merges independent repos and release processes
• ➖ More complex governance/permissions and potentially larger CI impact
• ➖ Doesn’t fit if repos must remain independently consumable and versioned

3. Use a purpose-built release tool (e.g., release-please / changesets-style)

• ➕ Automates versioning, tagging, and changelog generation consistently
• ➕ Often provides built-in resume/rollback semantics
• ➖ May not map cleanly to Maven Release Plugin semantics and tag-driven signed deploy workflow
• ➖ Still needs custom logic for Central availability gating and cross-repo adoption commits
• ➖ Tooling adoption/learning curve and potential policy mismatches

Recommendation: The PR’s approach (local orchestrator that drives each repo’s existing release:prepare flow, then waits for Maven Central availability) is a pragmatic fit given the repos remain independent and CI already owns the signed deploy. Consider a future workflow_dispatch-based CI orchestrator only if local Docker/Maven prerequisites become a recurring pain point or you need a stronger audit trail; otherwise this script keeps the release mechanics close to the developer workflow while preserving the current tag-triggered deploy model.

Files changed (3) +600 / -0

Enhancement (1) +440 / -0

release-all.ps1Add coordinated multi-repo release orchestrator with pre-flight and Central gating +440/-0

Add coordinated multi-repo release orchestrator with pre-flight and Central gating

• Implements a PowerShell script to release parent/core/spring-boot in dependency order with interactive version planning, pre-flight git/Docker checks, and optional dry-run mode. Automates downstream adoption commits (POM parent/property bumps), runs 'mvn release:prepare', supports subset/resume via '-Modules', and polls Maven Central to ensure upstream artifacts are published before releasing dependents.

release-all.ps1

Documentation (2) +160 / -0

README.adocDocument sibling-repo layout, dependency order, and release entrypoint +39/-0

Document sibling-repo layout, dependency order, and release entrypoint

• Adds an orientation README describing the three-repo structure, required release order (parent -> core -> spring-boot), and how cross-references are pinned to released upstream versions. Points readers to the detailed release procedure and the orchestrator script.

README.adoc

RELEASING.adocAdd end-to-end release runbook with dry-run, manual fallback, and rollback steps +121/-0

Add end-to-end release runbook with dry-run, manual fallback, and rollback steps

• Introduces a detailed release procedure explaining the tag-triggered CI deploy model, local 'release:prepare' responsibilities, prerequisites, and the one-command orchestrated path. Includes manual command sequences per repo, rollback guidance, and post-release verification checks.

RELEASING.adoc

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Fetch failure not detected ✓ Resolved 🐞 Bug ☼ Reliability

Description

Assert-Releasable runs git fetch origin but does not check its exit code, so a failed fetch can
leave a stale refs/remotes/origin/<branch> and incorrectly pass the “level with origin” guard.
This can allow the script to proceed into release:prepare and create local commits/tags before
later failing on push due to the remote actually being ahead.

Code

release-all.ps1[R202-210]

+    & git -C $RepoPath fetch origin --quiet | Out-Null
+    $remoteRef = & git -C $RepoPath rev-parse --verify --quiet "refs/remotes/origin/$branch"
+    if (-not $remoteRef) {
+        throw "[$Name] branch '$branch' has no origin/$branch -- push it to origin first."
+    }
+    $localRef = (& git -C $RepoPath rev-parse 'HEAD').Trim()
+    if ($localRef -ne $remoteRef.Trim()) {
+        throw "[$Name] branch '$branch' is not level with origin/$branch. Pull/push so they match, then re-run."
+    }

Evidence

The script executes git fetch origin and immediately reads refs/remotes/origin/$branch without
any $LASTEXITCODE check; if fetch fails, the ref read can be stale and the “level” check becomes
unreliable.

release-all.ps1[188-210]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`Assert-Releasable` performs `git fetch origin` but ignores failures. In PowerShell, external command non-zero exit codes do not automatically throw, so the subsequent comparison against `refs/remotes/origin/<branch>` can be based on stale tracking refs and incorrectly pass.

## Issue Context
This pre-flight check is meant to ensure the release tag is cut from commits already present on `origin`. If `fetch` fails (network/auth), the script can proceed and only fail later during `release:prepare` push, after local release state has been created.

## Fix Focus Areas
- release-all.ps1[188-210]

## Suggested fix
1. After `git fetch origin`, check `$LASTEXITCODE` and `throw` on non-zero.
2. (Optional but stronger) Replace the equality check with an ahead/behind check after a successful fetch, e.g. `git rev-list --left-right --count HEAD...origin/$branch` and ensure both counts are 0.
3. Consider also validating exit codes for other remote-dependent commands like `git ls-remote` used by `Test-RemoteTagExists`.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Release version validation too loose ✓ Resolved 🐞 Bug ≡ Correctness

Description

Read-ReleaseVersion accepts inputs that merely start with digits/dots (missing end anchor), but
Get-NextDevelopmentVersion assumes the last dot-separated segment is an integer. A value like
1.2.3-rc1 passes validation and then crashes when computing the default next development version
due to [int] conversion failure.

Code

release-all.ps1[R144-170]

+function Get-NextDevelopmentVersion {
+    param([string] $ReleaseVersion)
+    $parts = $ReleaseVersion -split '\.'
+    $parts[-1] = ([int] $parts[-1] + 1).ToString()
+    return ($parts -join '.') + '-SNAPSHOT'
+}
+
+function Read-WithDefault {
+    param([string] $Prompt, [string] $Default)
+    $answer = Read-Host "$Prompt [$Default]"
+    if ([string]::IsNullOrWhiteSpace($answer)) { return $Default }
+    return $answer.Trim()
+}
+
+function Read-ReleaseVersion {
+    param([string] $Name, [string] $Default)
+    while ($true) {
+        $value = Read-WithDefault "  [$Name] release version" $Default
+        if ($value -match '-SNAPSHOT$') {
+            Write-Host "      Release version must not end with -SNAPSHOT." -ForegroundColor Red
+            continue
+        }
+        if ($value -notmatch '^\d+(\.\d+)+') {
+            Write-Host "      Expected a numeric version like 1.2.3." -ForegroundColor Red
+            continue
+        }
+        return $value

Evidence

The release-version check allows trailing non-numeric content, while the next-version helper
increments the last segment via [int] cast; the planning loop calls this helper to produce the
default next development version, so invalid-but-accepted inputs will crash the script during
planning.

release-all.ps1[144-172]
release-all.ps1[343-354]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The release version prompt validates using a start-anchored regex only (`^\d+(\.\d+)+`), which allows suffixes (e.g. `1.2.3-rc1`). The script then calls `Get-NextDevelopmentVersion`, which casts the final dot segment to `[int]`, causing a runtime exception for such inputs.

## Issue Context
This crash happens immediately while planning the release (before the actual Maven operations), because the script computes the default next development version as `Get-NextDevelopmentVersion $release`.

## Fix Focus Areas
- release-all.ps1[144-172]
- release-all.ps1[343-354]

## Suggested fix
1. Make `Read-ReleaseVersion` enforce the whole string is numeric-dot segments by anchoring the regex, e.g. `'^\d+(\.\d+)+$'`.
2. Optionally also tighten `Read-DevelopmentVersion` to require a numeric base + `-SNAPSHOT`, e.g. `'^\d+(\.\d+)+-SNAPSHOT$'`.
3. Defensive hardening: in `Get-NextDevelopmentVersion`, validate the last segment is numeric before casting and throw a clear error if not (in case future validation is relaxed again).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[coderabbitai]

Actionable comments posted: 3

🤖 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 `@release-all.ps1`:
- Around line 274-299: The Invoke-Adopt flow only updates upstream versions when
parent/core are explicitly selected, which causes subset releases like
core,spring-boot to skip required upstream adoption. Update Invoke-Adopt to
carry adopt versions for omitted upstreams before the release loop, either by
prompting for the missing parent/core versions or resolving them from existing
tags, and then use those resolved values in the existing Commit-AdoptBump and
Invoke-Mvnw paths for the core and spring-boot branches.
- Around line 158-183: The version prompts in Read-ReleaseVersion and
Read-DevelopmentVersion are too loose and currently allow non-final release
strings like 1.2.3-rc1 and invalid snapshot prefixes like foo-SNAPSHOT. Tighten
the regex checks so Read-ReleaseVersion only accepts plain numeric release
versions with no suffixes, and Read-DevelopmentVersion only accepts a numeric
version ending in -SNAPSHOT. Keep the existing prompt flow and error messages,
but update the validation logic in these two functions to reject any extra
qualifiers.
- Around line 202-209: The branch sync check in release-all.ps1 can continue
after a failed git fetch and use stale refs, so make the fetch step fail fast
before reading refs/remotes/origin/$branch. Update the fetch logic near the repo
validation block to explicitly detect a non-zero git -C $RepoPath fetch origin
exit and throw immediately, so the later rev-parse comparison only runs when
fetch succeeds. Use the existing branch-check flow and variables ($RepoPath,
$branch, $remoteRef, $localRef) to keep the fix localized.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7af71064-cd91-43c6-b9a5-f358a3128629

📥 Commits

Reviewing files that changed from the base of the PR and between 21a522d and b7e5797.

📒 Files selected for processing (3)

• README.adoc
• RELEASING.adoc
• release-all.ps1

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift

Subset runs cannot adopt already-released upstreams.

Invoke-Adopt only bumps parent/core when that upstream is also in $Selected. A resumed run like -Modules core,spring-boot therefore skips the parent bump entirely and can release core/spring-boot against stale upstream versions, even though the docs advertise that flow. Please carry adopt versions for omitted upstreams too (for example by prompting for them or resolving them from tags) before entering the release loop.

🧰 Tools

🪛 PSScriptAnalyzer (1.25.0)

[info] 282-282: Cmdlet 'Commit-AdoptBump' has positional parameter. Please use named parameters instead of positional parameters when calling a command.

(PSAvoidUsingPositionalParameters)

---

[info] 291-291: Cmdlet 'Commit-AdoptBump' has positional parameter. Please use named parameters instead of positional parameters when calling a command.

(PSAvoidUsingPositionalParameters)

---

[info] 298-298: Cmdlet 'Commit-AdoptBump' has positional parameter. Please use named parameters instead of positional parameters when calling a command.

(PSAvoidUsingPositionalParameters)

🤖 Prompt for 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.

In `@release-all.ps1` around lines 274 - 299, The Invoke-Adopt flow only updates
upstream versions when parent/core are explicitly selected, which causes subset
releases like core,spring-boot to skip required upstream adoption. Update
Invoke-Adopt to carry adopt versions for omitted upstreams before the release
loop, either by prompting for the missing parent/core versions or resolving them
from existing tags, and then use those resolved values in the existing
Commit-AdoptBump and Invoke-Mvnw paths for the core and spring-boot branches.

[coderabbitai]

Actionable comments posted: 1

🤖 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 `@release-all.ps1`:
- Around line 217-220: The remote tag lookup in Test-RemoteTagExists currently
treats every empty git ls-remote result as a missing tag, which can hide network
or auth failures. Update this function to check the exit status of the git -C
$RepoPath ls-remote --tags origin refs/tags/$Tag call and throw an error when
the remote query fails instead of returning false. Keep the fix localized to
Test-RemoteTagExists so the release resume flow stops early on lookup errors
rather than continuing into release:prepare.

🪄 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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 78809b03-c6c1-481b-b844-f89ff5daf72a

📥 Commits

Reviewing files that changed from the base of the PR and between b7e5797 and fa099c9.

📒 Files selected for processing (3)

• README.adoc
• RELEASING.adoc
• release-all.ps1

✅ Files skipped from review due to trivial changes (2)

• README.adoc
• RELEASING.adoc

[jeffjensen]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.