From e2d5bfbafcf85a6abe9c3b69e27c70e188e319b3 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 15 Sep 2026 20:26:13 +0800 Subject: [PATCH 1/8] build(deps-dev): bump maven-deploy-plugin to 3.2.0 (#16) Bumps [org.apache.maven.plugins:maven-deploy-plugin](https://github.com/apache/maven-deploy-plugin) from 3.1.4 to 3.2.0. - [Release notes](https://github.com/apache/maven-deploy-plugin/releases) - [Commits](https://github.com/apache/maven-deploy-plugin/compare/maven-deploy-plugin-3.1.4...maven-deploy-plugin-3.2.0) --- updated-dependencies: - dependency-name: org.apache.maven.plugins:maven-deploy-plugin dependency-version: 3.2.0 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 4f5e2b9..1a2f250 100644 --- a/pom.xml +++ b/pom.xml @@ -29,7 +29,7 @@ 0.11.0 3.5.0 3.16.0 - 3.1.4 + 3.2.0 3.2.8 3.5.2 3.1.4 From 74765d38dd1aa5f0d4519097415f9e71cfa2650c Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 15 Sep 2026 20:27:40 +0800 Subject: [PATCH 2/8] build(deps-dev): bump maven-install-plugin to 3.2.0 (#18) Bumps [org.apache.maven.plugins:maven-install-plugin](https://github.com/apache/maven-install-plugin) from 3.1.4 to 3.2.0. - [Release notes](https://github.com/apache/maven-install-plugin/releases) - [Commits](https://github.com/apache/maven-install-plugin/compare/maven-install-plugin-3.1.4...maven-install-plugin-3.2.0) --- updated-dependencies: - dependency-name: org.apache.maven.plugins:maven-install-plugin dependency-version: 3.2.0 dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 1a2f250..2e0a726 100644 --- a/pom.xml +++ b/pom.xml @@ -32,7 +32,7 @@ 3.2.0 3.2.8 3.5.2 - 3.1.4 + 3.2.0 3.5.1 3.12.0 3.5.0 From 7e17d10a0379b1035a9d1b524975d2a65763d2ee Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 15 Sep 2026 20:28:43 +0800 Subject: [PATCH 3/8] build(deps): bump selenium-java to 4.49.0 (#19) Bumps [org.seleniumhq.selenium:selenium-java](https://github.com/SeleniumHQ/selenium) from 4.48.0 to 4.49.0. - [Release notes](https://github.com/SeleniumHQ/selenium/releases) - [Commits](https://github.com/SeleniumHQ/selenium/compare/selenium-4.48.0...selenium-4.49.0) --- updated-dependencies: - dependency-name: org.seleniumhq.selenium:selenium-java dependency-version: 4.49.0 dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 2e0a726..c29c0a2 100644 --- a/pom.xml +++ b/pom.xml @@ -41,7 +41,7 @@ 25 3.5.19 UTF-8 - 4.48.0 + 4.49.0 2.0.18 From 91e44faef309650687803d2722c62027a7fc1f81 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 15 Sep 2026 20:31:53 +0800 Subject: [PATCH 4/8] build(deps): bump guava to 33.7.1-jre (#20) Bumps [com.google.guava:guava](https://github.com/google/guava) from 33.6.0-jre to 33.7.1-jre. - [Release notes](https://github.com/google/guava/releases) - [Commits](https://github.com/google/guava/commits) --- updated-dependencies: - dependency-name: com.google.guava:guava dependency-version: 33.7.1-jre dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index c29c0a2..5011a25 100644 --- a/pom.xml +++ b/pom.xml @@ -20,7 +20,7 @@ 2.14.0 - 33.6.0-jre + 33.7.1-jre 3.2.2 26.1.0 1.37 From f222fcd840a5bf7a1a8e84377c13e02804cf018a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 15 Sep 2026 20:32:30 +0800 Subject: [PATCH 5/8] build(deps): bump slf4j-api to 2.0.19 (#17) Bumps org.slf4j:slf4j-api from 2.0.18 to 2.0.19. --- updated-dependencies: - dependency-name: org.slf4j:slf4j-api dependency-version: 2.0.19 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 5011a25..2d7ab96 100644 --- a/pom.xml +++ b/pom.xml @@ -42,7 +42,7 @@ 3.5.19 UTF-8 4.49.0 - 2.0.18 + 2.0.19 From 6ee3d08445c5b01b91845c15c36747ec1a9244f5 Mon Sep 17 00:00:00 2001 From: allurx Date: Tue, 15 Sep 2026 20:39:46 +0800 Subject: [PATCH 6/8] ci: complete release checks and document merge policy (#21) The public Maven Central check currently omits sources and Javadoc JARs. Check all 17 published artifacts, and require release-note scope review and breaking-change migration guidance before declaring a release complete. Document the branch merge policy and GitHub protection settings: squash short-lived branches into dev, and preserve shared ancestry with merge commits for dev-to-main releases. Validation: - actionlint and Markdown link/anchor checks passed. - All 17 v3.0.0 artifacts downloaded successfully from public Maven Central. - All eight simulated sources/Javadoc download failures stopped the check with a nonzero exit. - GitHub rules and environment settings were independently read back and verified. The file diff is limited to .github/workflows/release.yml, AGENTS.md, and docs/ci-cd.md. Branch ancestry includes existing main release merge commits; the new change is 17ee5ea. --- .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. From 7345b6d42b03ff5e6d7a916a6f63570420f0c2c8 Mon Sep 17 00:00:00 2001 From: allurx Date: Tue, 15 Sep 2026 20:51:55 +0800 Subject: [PATCH 7/8] docs: synchronize dev after each release --- AGENTS.md | 1 + docs/ci-cd.md | 13 ++++++++++--- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index d271a80..c869998 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,6 +17,7 @@ ## 分支与合并 - 短期功能、修复和依赖更新分支合入 `dev` 时使用 `Squash and merge`，每个 PR 保持一个完整意图。 - `dev` 与 `main` 是长期分支；`dev → main` 的发布 PR 使用 `Create a merge commit`，保留共同祖先，避免后续发布 PR 重复包含已压缩的提交。执行合并前核对 PR 的 base/head，并显式选择对应方式，不依赖 GitHub 默认选项。 +- 发布验证完成后，将已验证的 `main` 发布提交同步回 `dev`：已包含时无需合并，可快进时使用 fast-forward，已分叉时使用普通 merge，保留 `dev` 的后续改动；不用 Squash。`dev` 更新后推送并核对 CI，具体步骤见发布文档。 ## 发布 - 执行发布前读取 [CI/CD 与发布流程](docs/ci-cd.md#release)。用户明确要求发布指定版本时，按该流程完成本次发布所需的版本修改、验证、提交与推送、合入 main、创建并推送 tag 和结果核实；范围明确时不逐步重复确认。 diff --git a/docs/ci-cd.md b/docs/ci-cd.md index b92f1ad..8b4e13f 100644 --- a/docs/ci-cd.md +++ b/docs/ci-cd.md @@ -42,10 +42,11 @@ or database compatibility. See [the workflow](../.github/workflows/ci.yml) for t `dev` and `main` are long-lived branches. Use the merge policy recorded in [AGENTS.md](../AGENTS.md#分支与合并): -| Pull request | Merge method | +| Integration | 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 | +| Synchronize the verified `main` release commit → `dev` | Fast-forward when possible; use a normal merge commit if the branches have diverged; do nothing if already included | 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). @@ -108,7 +109,12 @@ include the workflow files in the release commit. 6. Follow both release jobs through completion. Confirm that the public Central 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 + guidance for breaking changes. +7. Update local `dev` from `origin/dev` with `git pull --ff-only`, then synchronize + the verified `main` release commit into it. If already included, no merge is + needed. Otherwise, fast-forward when possible or use a normal merge commit to + preserve subsequent work on `dev`; do not squash. If `dev` advances, push it and + wait for its CI to pass. Then report the version, release commit SHA, tag and release links. The person or agent performing the release owns step 4. Git tag operations and the @@ -119,7 +125,8 @@ performs its own build and tests after the tag is pushed. A request such as “帮我把当前工程发布为 vX.Y.Z” authorizes the necessary version updates, verification, commits, pushes, integration into `main`, tag creation and -push, and publication checks for that release. The agent follows the shared +push, publication checks, and synchronization of the verified release commit back +into `dev`. The agent follows the shared procedure, queries and waits for CI itself, and completes the authorized steps without requesting confirmation for each one. If the version or release scope is materially unclear, establish it before the dependent actions. From dc3d693f7b11840939fe553e77bad66935ba4a14 Mon Sep 17 00:00:00 2001 From: allurx Date: Tue, 15 Sep 2026 21:09:53 +0800 Subject: [PATCH 8/8] chore(release): prepare 3.0.1 --- kit-base/pom.xml | 2 +- kit-json/pom.xml | 2 +- kit-mybatis/pom.xml | 2 +- kit-selenium/pom.xml | 2 +- pom.xml | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/kit-base/pom.xml b/kit-base/pom.xml index 0efbf59..5ad8731 100644 --- a/kit-base/pom.xml +++ b/kit-base/pom.xml @@ -4,7 +4,7 @@ io.allurx.kit kit - 3.0.0 + 3.0.1 kit-base diff --git a/kit-json/pom.xml b/kit-json/pom.xml index 16d0d14..d664277 100644 --- a/kit-json/pom.xml +++ b/kit-json/pom.xml @@ -4,7 +4,7 @@ io.allurx.kit kit - 3.0.0 + 3.0.1 kit-json diff --git a/kit-mybatis/pom.xml b/kit-mybatis/pom.xml index 8948780..a80ef2f 100644 --- a/kit-mybatis/pom.xml +++ b/kit-mybatis/pom.xml @@ -4,7 +4,7 @@ io.allurx.kit kit - 3.0.0 + 3.0.1 kit-mybatis diff --git a/kit-selenium/pom.xml b/kit-selenium/pom.xml index c29b254..e864c3f 100644 --- a/kit-selenium/pom.xml +++ b/kit-selenium/pom.xml @@ -4,7 +4,7 @@ io.allurx.kit kit - 3.0.0 + 3.0.1 kit-selenium diff --git a/pom.xml b/pom.xml index 2d7ab96..1fddbac 100644 --- a/pom.xml +++ b/pom.xml @@ -4,7 +4,7 @@ io.allurx.kit kit - 3.0.0 + 3.0.1 pom kit