maven-release-validation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Maven Release Validation

Maven 发布验证

Turn a Maven release request into an evidence-backed checklist. Treat source verification, Git synchronization, repository publication, clean-cache consumption, CI, and runtime readiness as separate gates. Never infer a later gate from an earlier one.

将 Maven 发布请求转化为有证据支撑的检查清单。将源码验证、Git 同步、仓库发布、空缓存消费、CI 和运行时就绪状态视为相互独立的关卡。绝不能根据较早关卡的结果推断后续关卡已通过。

Quick start

快速开始

Typical requests:

“用
```
$maven-release-validation
```
验证三个维护分支能否发布到阿里云 Maven。”
“审计这次 SNAPSHOT 发布，确认 GitHub、Codeup 和远端构件一致。”
“为下游项目做空缓存消费验证，并给出可复核的发布报告。”

Start by discovering the real repository/worktree, current branch, dirty state, wrapper, POM hierarchy, repository configuration, and existing release scripts. If

.codegraph/

exists, use CodeGraph before text search for code-structure questions. Do not create/switch branches, commit, push, deploy, delete caches, or modify repository settings unless the user requested that mutation.

典型请求：

“用
```
$maven-release-validation
```
验证三个维护分支能否发布到阿里云 Maven。”
“审计这次 SNAPSHOT 发布，确认 GitHub、Codeup 和远端构件一致。”
“为下游项目做空缓存消费验证，并给出可复核的发布报告。”

首先发现真实的 repository/worktree、当前分支、dirty 状态、wrapper、POM 层级、仓库配置和现有发布脚本。如果存在

.codegraph/

，针对代码结构问题，应先使用 CodeGraph，再使用文本搜索。除非用户明确要求执行变更操作，否则不得创建或切换分支、commit、push、deploy、删除缓存或修改仓库设置。

Inputs and release matrix

输入和发布矩阵

Build a matrix before executing:

Field	Required evidence
Release line	exact branch/ref and working directory
Toolchain	required JDK, Maven/wrapper version, active `java -version` and Maven runtime
Coordinates	groupId/artifactId/version and SNAPSHOT vs release
Scope	expected reactor/modules and changed files
Remotes	exact Git remote names/URLs and target refs
Repository	repository ID and configured destination; never print credentials
Consumers	minimal external consumer(s) and artifacts/APIs they exercise
Gates	tests, Enforcer, signing/SBOM/license/security/CI requirements and approved skips

If a material value is unknown, continue with read-only discovery. Before an external mutation, stop with

缺少[具体项]；请提供或确认[补充方式]

. Never guess credentials, repository IDs, branches, versions, or release commands.

执行前先构建矩阵：

字段	必需证据
发布线	精确的 branch/ref 和工作目录
工具链	所需的 JDK、Maven/wrapper 版本，以及当前生效的 `java -version` 和 Maven runtime
构件坐标	groupId/artifactId/version，以及 SNAPSHOT 或 release
范围	预期的 reactor/模块和变更文件
远端	精确的 Git remote 名称/URL 和目标 refs
仓库	repository ID 和配置的目标位置；绝不打印凭据
消费方	最小的外部 consumer 及其测试的构件/API
关卡	测试、Enforcer、signing/SBOM/license/security/CI 要求及已获批准的跳过项

如果某个关键值未知，应继续进行只读发现。在执行外部变更前，停止并提示：

缺少[具体项]；请提供或确认[补充方式]

。绝不能猜测凭据、repository ID、分支、版本或发布命令。

Gate sequence

关卡顺序

Read references/release-checklist.md before running or auditing a release. Use its evidence table as the report skeleton.

Baseline — identify Git root/worktrees, preserve dirty/untracked work, enumerate exact changed files, and record local/tracking/remote SHAs.
Per-line verification — activate each line’s actual JDK/Maven contract and run the project’s full required verification. Record reactor/module counts and test totals, failures, errors, and skips. A compiler from another line is not proof.
Source synchronization — when authorized, commit branch-specific diffs separately and push to every required remote. Verify each remote ref resolves to the intended commit; upload output alone is insufficient.
Publication — publish lines serially unless repository semantics prove parallel publication safe. A robust default is oldest JDK line to newest. Use the repository’s established wrapper/settings/profile. If full tests already passed immediately beforehand, deploy may skip re-running tests only when project policy permits; do not silently bypass Enforcer, signing, license, SBOM, security, or repository gates.
Remote proof — require complete reactor success and confirm the expected POM/JAR plus required sources, javadoc, checksums, signatures, and metadata are visible remotely. Partial uploads or a running process are
```
in_progress
```
, not
```
passed
```
.
Clean-cache consumption — create a new isolated temporary Maven local repository for each proof. Resolve from configured remote repositories without relying on the producer checkout or ordinary local cache. Test parent/BOM import, direct dependency resolution, and a minimal compile/test or startup path for changed runtime adapters.
Final reconciliation — compare local HEAD, tracking ref, every required Git remote SHA, published version/timestamp, and consumer result. Report CI and runtime deployment separately if they were not observed.

Stop serial publication on the first failed line. Preserve logs and already published evidence, mark later lines

not_run

, and do not retry or overwrite artifacts without explicit authorization and a repository-safe recovery plan.

在运行或审计发布之前，阅读 references/release-checklist.md。使用其中的证据表作为报告骨架。

基线 — 确定 Git root/worktrees，保留 dirty/untracked 工作，枚举确切的变更文件，并记录 local/tracking/remote SHA。
逐发布线验证 — 启用每条发布线实际要求的 JDK/Maven 约定，并运行项目要求的完整验证。记录 reactor/模块数量、测试总数、失败数、错误数和跳过数。来自另一条发布线的编译器不能作为证明。
源码同步 — 获得授权后，分别提交各分支专属的 diff，并 push 到每个必需的 remote。验证每个 remote ref 都解析到预期 commit；仅有上传输出并不足够。
发布 — 除非仓库语义能够证明并行发布安全，否则应串行发布各发布线。稳健的默认顺序是从最旧的 JDK 发布线到最新的发布线。使用仓库既有的 wrapper/settings/profile。如果完整测试刚刚已经通过，只有在项目策略允许时，deploy 才能跳过再次运行测试；不得在未说明的情况下绕过 Enforcer、signing、license、SBOM、security 或 repository 关卡。
远端证明 — 要求整个 reactor 成功，并确认预期的 POM/JAR，以及所需的 sources、javadoc、checksums、signatures 和 metadata 已在远端可见。部分上传或仍在运行的进程应标记为
```
in_progress
```
，而不是
```
passed
```
。
空缓存消费 — 每次证明都创建一个新的隔离临时 Maven local repository。从已配置的 remote repositories 解析依赖，不依赖 producer checkout 或普通本地缓存。测试 parent/BOM import、直接依赖解析，以及针对变更的 runtime adapters 的最小 compile/test 或 startup 路径。
最终核对 — 比较 local HEAD、tracking ref、每个必需 Git remote 的 SHA、已发布版本/时间戳和 consumer 结果。如果未观察到 CI 和 runtime deployment，应分别报告。

第一条发布线失败时，停止串行发布。保留日志和已经发布的证据，将后续发布线标记为

not_run

，并且在没有明确授权和仓库安全的恢复方案时，不得重试或覆盖构件。

Evidence rules

证据规则

Use
```
passed
```
,
```
failed
```
,
```
in_progress
```
,
```
not_run
```
, or
```
skipped
```
for every gate.
A skip is never a pass. State who/what authorized it and the residual risk.
Distinguish observed command output from inference. Do not claim current remote state from an older screenshot, summary, or local cache.
Redact tokens, passwords, private repository credentials, and sensitive URLs from commands and logs.
Prefer an isolated repository such as a directory created by
```
mktemp -d
```
; remove it only when safe and authorized. Never delete the user’s normal Maven repository for “clean-cache” proof.
For SNAPSHOTs, capture the resolved timestamp/build number where available so the consumer proof can be tied to the publication.

每个关卡使用
```
passed
```
、
```
failed
```
、
```
in_progress
```
、
```
not_run
```
或
```
skipped
```
。
skipped 永远不等于 passed。说明是谁或什么授权了跳过，以及剩余风险。
区分观察到的命令输出和推断。不得依据较早的截图、摘要或本地缓存声称当前远端状态。
从命令和日志中脱敏 tokens、密码、私有仓库凭据和敏感 URL。
优先使用隔离仓库，例如通过
```
mktemp -d
```
创建的目录；仅在安全且获得授权时删除。绝不能为了进行“空缓存”证明而删除用户的普通 Maven repository。
对于 SNAPSHOT，尽可能捕获解析出的时间戳/build number，以便将 consumer 证明与本次发布关联起来。

Output

输出

Return a compact per-line table plus blockers and next actions. Include commands executed (with secrets redacted), log paths, module/test counts, exact SHAs, remote artifact evidence, consumer evidence, skips, and timestamps. If the request is checklist-only, produce planned commands with

not_run

status and do not imply execution.

For failure wording and misleading shortcuts, read references/anti-patterns.md. For edge cases such as SNAPSHOT metadata, partial publication, Maven 4 warnings, or CI/runtime boundaries, read references/faq.md.

返回紧凑的逐发布线表格，以及阻塞项和后续操作。包含已执行的命令（敏感信息已脱敏）、日志路径、模块/测试数量、精确 SHA、远端构件证据、consumer 证据、跳过项和时间戳。如果请求仅要求检查清单，则输出状态为

not_run

的计划命令，不得暗示已经执行。

有关失败措辞和容易产生误导的捷径，请阅读 references/anti-patterns.md。有关 SNAPSHOT metadata、部分发布、Maven 4 warnings 或 CI/runtime 边界等边缘情况，请阅读 references/faq.md。

Capability boundaries

能力边界

Well suited: multi-branch release readiness; private Maven publication audits; empty-cache downstream proofs; Git/repository evidence reconciliation.
Needs project material: credentials/settings; exact branch matrix; required quality gates; consumer examples; repository overwrite/retention policy.
Out of scope: inventing credentials; bypassing required gates; destructive cache cleanup; declaring production runtime readiness from Maven publication alone; changing release architecture without a separate approved design.

适用场景： 多分支发布就绪评估；私有 Maven 发布审计；空缓存下游证明；Git/repository 证据核对。
需要项目材料： 凭据/settings；精确的分支矩阵；必需的质量关卡；consumer 示例；仓库覆盖/保留策略。
不在范围内： 伪造凭据；绕过必需关卡；破坏性缓存清理；仅凭 Maven 发布就宣称生产 runtime 已就绪；未经单独批准的设计而改变发布架构。