From 17ee5ea442bfbacee5681177093f08f42b7cfd41 Mon Sep 17 00:00:00 2001 From: allurx Date: Tue, 15 Sep 2026 20:15:51 +0800 Subject: [PATCH] ci: complete artifact checks and document release safeguards --- .github/workflows/release.yml | 9 ++++--- AGENTS.md | 6 ++++- docs/ci-cd.md | 50 +++++++++++++++++++++++++---------- 3 files changed, 46 insertions(+), 19 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index f491cf8..fb2c140 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -111,13 +111,14 @@ jobs: run: | # 在独立 job 中确认消费者能下载各模块；失败后可单独重跑，不会重新上传。 for module in kit kit-base kit-json kit-mybatis kit-selenium; do - extensions=(pom) - if [[ $module != kit ]]; then extensions+=(jar); fi - for extension in "${extensions[@]}"; do + # 父模块仅发布 POM；库模块同时核对主 JAR、源码和 Javadoc。 + suffixes=(.pom) + if [[ $module != kit ]]; then suffixes+=(.jar -sources.jar -javadoc.jar); fi + for suffix in "${suffixes[@]}"; do # 对 Central 的短暂同步延迟保留有限重试，文件内容无需落盘。 curl --fail --silent --show-error --location \ --retry 12 --retry-all-errors --retry-delay 5 --retry-max-time 180 --max-time 30 \ - "https://repo.maven.apache.org/maven2/io/allurx/kit/$module/$KIT_VERSION/$module-$KIT_VERSION.$extension" \ + "https://repo.maven.apache.org/maven2/io/allurx/kit/$module/$KIT_VERSION/$module-$KIT_VERSION$suffix" \ --output /dev/null done done diff --git a/AGENTS.md b/AGENTS.md index 01a537e..d271a80 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,8 +14,12 @@ - 修改轮询行为时，使用已有 Clock / Sleeper 注入点验证次数、截止与异常边界；修改反射泛型 API 时，同时验证外部调用的编译类型和运行行为。 - JMH 与 JUnit 独立；普通测试通过不能作为性能证据。 +## 分支与合并 +- 短期功能、修复和依赖更新分支合入 `dev` 时使用 `Squash and merge`，每个 PR 保持一个完整意图。 +- `dev` 与 `main` 是长期分支；`dev → main` 的发布 PR 使用 `Create a merge commit`，保留共同祖先，避免后续发布 PR 重复包含已压缩的提交。执行合并前核对 PR 的 base/head，并显式选择对应方式，不依赖 GitHub 默认选项。 + ## 发布 - 执行发布前读取 [CI/CD 与发布流程](docs/ci-cd.md#release)。用户明确要求发布指定版本时，按该流程完成本次发布所需的版本修改、验证、提交与推送、合入 main、创建并推送 tag 和结果核实；范围明确时不逐步重复确认。 - 创建并推送正式 tag 前，由执行发布的 Agent 主动查询最终 main 发布提交 SHA 对应的 CI，等待其成功；缺少结果、运行中或未成功均不能视为通过，也不能用其他提交的成功结果代替。发布提交发生变化后重新核对；该检查由发布执行者负责，当前 CD 不查询此前的 CI 结果。 - 普通 CI 可使用 `-Prelease -Dgpg.skip=true` 执行到 `verify`，验证 sources / Javadoc 等发布产物；该命令不签名、不上传。正式发布启用 release profile，不跳过签名；发布相关变更须核验这些实际产物。 -- Central 上传、校验和公开发布分别核实；以 pom.xml 中发布插件配置及最终可下载组件为准，不能只凭 deploy 成功判断公开发布完成。确认 Central 制品可公开下载且 GitHub Release 已创建后，再报告发布完成，并提供版本、commit、tag 和发布链接。 +- Central 上传、校验和公开发布分别核实；以 pom.xml 中发布插件配置及最终可下载组件为准，不能只凭 deploy 成功判断公开发布完成。确认 Central 制品可公开下载且 GitHub Release 已创建，审核发布说明的变更范围并补齐破坏性变更的迁移要点后，再报告发布完成，并提供版本、commit、tag 和发布链接。 diff --git a/docs/ci-cd.md b/docs/ci-cd.md index 714f922..b92f1ad 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -37,6 +37,20 @@ including on failure. Tests use the module path; the real Chrome test skips unle `kit.selenium.chromePath` is supplied. Normal CI does not verify real browser startup or database compatibility. See [the workflow](../.github/workflows/ci.yml) for the invocation. +## Branches and merges + +`dev` and `main` are long-lived branches. Use the merge policy recorded in +[AGENTS.md](../AGENTS.md#分支与合并): + +| Pull request | Merge method | +| --- | --- | +| Short-lived feature, fix or dependency-update branch → `dev` | **Squash and merge**; keep one logical change per PR | +| Release from `dev` → `main` | **Create a merge commit**; preserve shared ancestry between releases | + +Squashing a long-lived branch can make later PRs include already-squashed commits +and repeat conflicts. See [GitHub's guidance on long-running branches](https://docs.github.com/en/pull-requests/reference/pull-request-merges#squashing-and-merging-a-long-running-branch). +Check the PR's base/head and explicitly select the appropriate merge method. + ## GitHub setup Create the `maven-central` Environment with: @@ -52,11 +66,16 @@ The token must be authorized for `io.allurx.kit`; publish the corresponding publ GPG key as required by Central. `setup-java` creates Maven settings with server ID `central`, matching the POM, and imports the signing key for the publishing job. -Limit the Environment to `v*` tags and choose Environment approval rules according -to repository policy. After a successful live CI run, configure its check as a branch -requirement for `dev` and `main`; protect release tags against updates and deletion. +Limit the Environment to tags matching `v*`. Require a pull request and a successful +`verify` check from GitHub Actions before merging into `main`; no additional human +approval or strict branch-update requirement is needed for this workflow. Protect +`v*` release tags against updates and deletion while allowing new tags to be created. Repository settings and secrets are configured separately from source changes. +In **Settings → General → Pull Requests**, enable **Allow squash merging** and +**Allow merge commits**, and disable **Allow rebase merging**. These repository-wide +options make both methods available; the merger follows the policy above for each PR. + Actions are pinned to commit SHAs. Dependabot proposes weekly Maven and Actions version updates to `dev`. Maven plugin versions, including the Help plugin used for release version checks, are managed in the root POM; workflows invoke the goals @@ -76,9 +95,9 @@ include the workflow files in the release commit. 2. Update the root POM's project version and all four child POMs' parent versions together. Run root `verify` with `release` unchecked and fix relevant failures. `install` is only needed by other local projects; it is not a release prerequisite. -3. Commit and push the release changes, wait for CI, then integrate them into `main` - according to the repository's review and merge rules. Update local `main` and - confirm a clean working tree. +3. Commit and push the release changes, wait for CI, then + merge the `dev` → `main` release PR with **Create a merge commit**. Update local + `main` with `git pull --ff-only` and confirm a clean working tree. 4. Record the final release commit SHA. Query the `CI` workflow run for that exact commit on `main` and wait for successful completion. A missing, pending, failed, cancelled or skipped run does not satisfy this check. A green result for another @@ -87,8 +106,10 @@ include the workflow files in the release commit. 5. Create the annotated `vMAJOR.MINOR.PATCH` tag on that verified commit and push that exact tag to trigger the `Release` workflow. 6. Follow both release jobs through completion. Confirm that the public Central - artifact checks pass and the GitHub Release exists, then report the version, - commit SHA, tag and release links. + artifact checks pass and the GitHub Release exists. Review the generated notes + against this release's changes, correct unrelated history, and add migration + guidance for breaking changes before reporting the version, commit SHA, tag and + release links. The person or agent performing the release owns step 4. Git tag operations and the current release workflow do not query earlier CI results. The release workflow @@ -144,10 +165,10 @@ The workflow has two jobs: One `clean deploy` builds, tests, generates sources/Javadoc, signs and publishes through the Central plugin, waiting for `PUBLISHED`. Logs and Surefire reports are retained for 90 days when report upload succeeds. -2. **`github-release`** downloads the five POMs and four main JARs from public Maven - Central, then creates the GitHub Release with generated notes. An existing release - is preserved. Rerunning only this job repeats the public checks and GitHub Release - creation without rebuilding or deploying. +2. **`github-release`** downloads the five POMs and twelve main, sources and Javadoc + JARs from public Maven Central, then creates the GitHub Release with generated + notes. An existing release is preserved. Rerunning only this job repeats the + public checks and GitHub Release creation without rebuilding or deploying. The [release workflow](../.github/workflows/release.yml) owns the publishing command and its options. @@ -163,9 +184,10 @@ and its options. Maven log and deployment status in Central Portal first. Follow an in-progress deployment there; do not blindly rerun the entire release or upload the version again. - If the `publish` job failed but Central reports `PUBLISHED`, manually confirm that - the five POMs and four main JARs can be downloaded from public Maven Central. Then, - if the GitHub Release is missing, finish with + the five POMs and twelve main, sources and Javadoc JARs can be downloaded from + public Maven Central. Then, if the GitHub Release is missing, finish with `gh release create --repo allurx/kit --verify-tag --generate-notes`. + Review the generated notes using the same release procedure. - If only the final GitHub Release job failed, rerunning that failed job is sufficient. Published Central coordinates are immutable. Fix faulty public content in a new version.