Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,8 @@ jobs:
- name: Build, test and enforce coverage gate(与 ci.yml 相同命令)
run: mvn -B -ntp verify

- name: Publish to Maven Central(严格排在测试全绿之后;autoPublish=false:
上传后停在 Portal 待发布状态,人工核对构件/签名/坐标后手动 Publish)
- name: Publish to Maven Central(严格排在测试全绿之后;autoPublish=true:
Portal 校验通过即自动发布,发布不可撤销、坐标永久公开)
env:
GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
run: mvn -B -ntp -P release -DskipTests deploy
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ Conventional Commits,body 用中文说明动机与影响:

1. 版本号同步到全部模块 pom:`mvn versions:set -DnewVersion=X.Y.Z` → `mvn versions:commit`,提交
2. 打 tag 并推送:`git tag vX.Y.Z && git push origin vX.Y.Z`
3. workflow 校验 tag 与 pom 版本一致后,先跑 `mvn -B -ntp verify`(与 CI 相同门禁),全绿后以 `mvn -P release deploy` 上传 Central Portal;autoPublish=false 时构件停在待发布状态,**人工核对后到 Portal 手动 Publish**(首次发版策略,详见 [docs/release-guide.md](docs/release-guide.md));失败即中止,不留半发布状态
3. workflow 校验 tag 与 pom 版本一致后,先跑 `mvn -B -ntp verify`(与 CI 相同门禁),全绿后以 `mvn -P release deploy` 上传 Central Portal;`autoPublish=true`(0.3.0 起),Portal 校验通过即自动发布,**发布不可撤销、坐标永久公开**——推 tag 前必须确认版本号(详见 [docs/release-guide.md](docs/release-guide.md));失败即中止,不留半发布状态

发布通道为 Sonatype **Maven Central Portal**(OSSRH 已于 2025-06 停服后的官方路径)。

Expand Down
26 changes: 12 additions & 14 deletions docs/release-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

> 版本:1.0(2026-08-29)| 适用:wop-java-sdk 0.1.0 首次发布
> 决策记录:namespace = `com.wanlianyida`(**DNS TXT 验证**,依赖 wanlianyida.com 域名控制权);
> 首次发布策略 = **autoPublish=false**(上传后人工核对再手动 Publish)
> 发布策略 = **autoPublish=true**(0.3.0 起:Portal 校验通过即自动发布,不可撤销)
> 概览见 [CONTRIBUTING.md §8](../CONTRIBUTING.md);自动化细节见 `.github/workflows/release.yml` 头部注释

## 0. 发版前检查结论(已完成,2026-08-29 实测)
Expand All @@ -12,7 +12,7 @@
| 构建链 | ✅ | `mvn -P release -DskipTests package` 预验通过,三模块 sources/javadoc jar 共 6 个全部生成 |
| 坐标 | ✅ | 父/子 pom 全部 `com.wanlianyida`,无 `com.wopplatform` 残留 |
| Central 元数据 | ✅ | name/description/url/licenses/developers/scm 齐备(Central 校验必备) |
| release profile | ✅ | maven-source 3.4.0 / javadoc 3.12.0(doclint=none)/ gpg 3.2.8(loopback)/ central-publishing 0.11.0(autoPublish=false) |
| release profile | ✅ | maven-source 3.4.0 / javadoc 3.12.0(doclint=none)/ gpg 3.2.8(loopback)/ central-publishing 0.11.0(autoPublish=true) |
| release.yml | ✅ | tag↔pom 版本一致性校验 → GPG 导入 → Secrets 注入 settings.xml → 测试全绿后 deploy |
| 远端 | ✅ | origin = `git@github.com:wop-platform/wop-java-sdk.git` |
| 测试/覆盖率 | ✅ | 208 tests 全绿;JaCoCo 聚合行 100.00% / 分支 100.00%(三模块门禁各 ≥98%) |
Expand Down Expand Up @@ -65,19 +65,17 @@ git tag v0.1.0 && git push origin v0.1.0
release.yml 自动执行:版本一致性校验 → GPG 密钥导入 → `mvn verify`(门禁再跑一遍)→
`mvn -P release -DskipTests deploy` 上传(source/javadoc/GPG 签名构件)。任一步失败即中止,不留半发布状态。

### 2.1 人工核对与手动发布(首次发版策略)
### 2.1 自动发布(autoPublish=true)

上传成功后构件处于**待发布**状态(autoPublish=false):
上传后 Portal 自动校验并发布,无需人工点击。CI 日志出现以下两行即完成:

1. Portal → **Publishing / Releases** 打开本次部署。
2. 核对:
- 三模块坐标 `com.wanlianyida:wop-sdk-{core,okhttp,jdkhttp}:0.1.0`
- 每构件四件套:主 jar / sources / javadoc / `.asc` 签名
- POM 元数据(licenses MIT、developers、scm 指向 wop-platform/wop-java-sdk)
3. 无误后点 **Publish**。
```
Uploaded bundle successfully, deployment name: Deployment, deploymentId: <uuid>
Deployment <uuid> has been successfully published
```

> **不可撤回提醒**:Central 发布后坐标永久公开、不可删除。发布前发现的任何问题,
> 直接在 Portal 丢弃(Discard)该部署,修完重新打 tag(删除 tag 重推即可,workflow 幂等)。
> **不可撤回提醒**:Central 发布后坐标永久公开、不可删除。上传前发现的任何问题,
> 直接丢弃(Discard)该部署,修完重新打 tag(删除 tag 重推即可,workflow 幂等)。
Comment on lines +77 to +78

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 中 · 丢弃说明无法阻止发布

当操作人员在上传前发现版本存在问题并按照丢弃说明操作时,指南会要求他们丢弃一个尚不存在的部署;上传后,autoPublish=true 会在验证通过后立即发布,因此没有可用于阻止错误发布的丢弃时限。

请用新的指导替换“丢弃并重新打标签”的恢复说明,明确指出:上传前没有可供丢弃的部署,而自动发布后也不存在丢弃时限。

提供给 AI 智能体的提示
在 `docs/release-guide.md` 第 77-78 行:

**丢弃说明无法阻止发布**

当操作人员在上传前发现版本存在问题并按照丢弃说明操作时,指南会要求他们丢弃一个尚不存在的部署;上传后,`autoPublish=true` 会在验证通过后立即发布,因此没有可用于阻止错误发布的丢弃时限。

请用新的指导替换“丢弃并重新打标签”的恢复说明,明确指出:上传前没有可供丢弃的部署,而自动发布后也不存在丢弃时限。
Original comment in English

🟡 Medium · Discard guidance cannot stop release

When an operator finds a release issue before upload and follows the discard instruction, the guide directs operators to discard a deployment that does not yet exist; after upload, autoPublish=true publishes it as soon as validation passes, leaving no discard window to stop an erroneous release.

Replace the discard-and-retag recovery instruction with guidance that reflects there is no deployment to discard before upload and no discard window after automatic publication.

Prompt for AI agents
In `docs/release-guide.md` at lines 77-78:

**Discard guidance cannot stop release**

When an operator finds a release issue before upload and follows the discard instruction, the guide directs operators to discard a deployment that does not yet exist; after upload, `autoPublish=true` publishes it as soon as validation passes, leaving no discard window to stop an erroneous release.

Replace the discard-and-retag recovery instruction with guidance that reflects there is no deployment to discard before upload and no discard window after automatic publication.


## 3. 阶段三:发版后验证

Expand Down Expand Up @@ -107,8 +105,8 @@ git commit -am "chore: bump version to 0.1.1-SNAPSHOT"
该域名的持续控制权 = namespace 的持续控制权。域名到期不影响已发布构件,
但将无法在该 namespace 下发布新版本。若域名非长期资产,唯一不依赖域名的
替代是 `io.github.wop-platform`(需全仓坐标迁移);**0.1.0 Publish 前是最后的低成本反悔窗口**。
2. **autoPublish=false 仅首次**:链路验证稳定后可改回 `true`(pom `central-publishing` 配置),
减少一次人工环节;保留 false 亦可,作为每版的例行核对点。
2. **autoPublish=true**(0.3.0 起):Portal 校验通过即自动发布,无需人工环节;
如需每版人工核对,改回 `false`(pom `central-publishing` 配置)。
3. **坐标决策一致性**:README 依赖示例、scm/developers(org=wop-platform)与 groupId(com.wanlianyida)
为有意组合(组织在 GitHub,发布坐标用自有域名);后续其他五语言 SDK 发布时保持同一 namespace 策略,
避免六仓坐标体系分裂。
Expand Down
2 changes: 1 addition & 1 deletion docs/wop-sdk-report-java.md
Original file line number Diff line number Diff line change
Expand Up @@ -216,7 +216,7 @@ ab986e6 test: 故障注入场景覆盖(协议层+双适配器网络层);do
| remote | origin = git@github.com:wop-platform/wop-java-sdk.git 已配置 |
| 测试/覆盖率 | 208 tests 全绿;聚合行/分支 100.00% |

**已按用户决策修正**:`autoPublish` true→false(首次发版人工核对后手动 Publish);release.yml 注释验证路径改为 DNS TXT(原注释写的 GitHub 仓库验证不适用于 com.wanlianyida)。
**已按用户决策修正**:`autoPublish` true→false(首次发版人工核对后手动 Publish);release.yml 注释验证路径改为 DNS TXT(原注释写的 GitHub 仓库验证不适用于 com.wanlianyida)。(0.3.0 起改回 `true`,见 CONTRIBUTING §8)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚪ 低 · 发布说明相互矛盾

当维护者查阅报告以了解当前发布流程时,docs/wop-sdk-report-java.md 声明发布需要手动点击 Publish,并提到 autoPublish=false;而发布指南则称 Portal 验证通过后会自动发布,因此读者会看到相互矛盾的说明。

更新报告中的发布策略描述及相关引用,使其与当前的自动发布流程一致。

另见 docs/release-guide.md:70。

提供给 AI 智能体的提示
在 `docs/wop-sdk-report-java.md` 第 219 行:

**发布说明相互矛盾**

当维护者查阅报告以了解当前发布流程时,`docs/wop-sdk-report-java.md` 声明发布需要手动点击 Publish,并提到 `autoPublish=false`;而发布指南则称 Portal 验证通过后会自动发布,因此读者会看到相互矛盾的说明。

更新报告中的发布策略描述及相关引用,使其与当前的自动发布流程一致。

另见 `docs/release-guide.md:70`。
Original comment in English

⚪ Low · Release instructions contradict each other

When a maintainer consults the report to understand the current release process, docs/wop-sdk-report-java.md says releases require manual Publish and refers to autoPublish=false, while the release guide says Portal validation publishes automatically, so readers get conflicting instructions.

Update the report’s release-policy description and reference to match the current automatic-publishing process.

Also at docs/release-guide.md:70.

Prompt for AI agents
In `docs/wop-sdk-report-java.md` at line 219:

**Release instructions contradict each other**

When a maintainer consults the report to understand the current release process, `docs/wop-sdk-report-java.md` says releases require manual Publish and refers to `autoPublish=false`, while the release guide says Portal validation publishes automatically, so readers get conflicting instructions.

Update the report’s release-policy description and reference to match the current automatic-publishing process.

Also at `docs/release-guide.md:70`.


**发版前唯一阻断项**:Central Portal namespace `com.wanlianyida` 的 DNS TXT 验证(需 wanlianyida.com 域名控制权,操作指引见会话回复)。

Expand Down
4 changes: 2 additions & 2 deletions pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -218,8 +218,8 @@
<extensions>true</extensions>
<configuration>
<publishingServerId>central</publishingServerId>
<!-- 首次发版策略:false = 上传后停在 Portal 待发布,人工核对后手动 Publish -->
<autoPublish>false</autoPublish>
<!-- 链路上线策略:true = Portal 校验通过后自动发布(发布不可撤销,坐标永久公开) -->
<autoPublish>true</autoPublish>

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 高 · 未经批准的制品会公开发布

当匹配的 v* 标签指向意外或恶意的提交,且该提交通过 mvn verify 时,发布工作流只检查标签与 POM 版本是否匹配以及 mvn verify 是否通过,随后 autoPublish=true 就会在没有人工审批环节的情况下发布带标签的制品,因此未经批准或恶意的制品会公开发布。

应在发布带标签的版本制品前要求明确的人工审批,而不是自动发布。

提供给 AI 智能体的提示
在 `pom.xml` 第 222 行:

**未经批准的制品会公开发布**

当匹配的 `v*` 标签指向意外或恶意的提交,且该提交通过 `mvn verify` 时,发布工作流只检查标签与 POM 版本是否匹配以及 `mvn verify` 是否通过,随后 `autoPublish=true` 就会在没有人工审批环节的情况下发布带标签的制品,因此未经批准或恶意的制品会公开发布。

应在发布带标签的版本制品前要求明确的人工审批,而不是自动发布。
Original comment in English

🟠 High · Unapproved artifacts publish publicly

When a matching v* tag points to an unintended or malicious commit that passes mvn verify, the release workflow checks only the tag-to-POM version and mvn verify, then autoPublish=true publishes the tagged artifacts without a human approval checkpoint, so unapproved or malicious artifacts become public.

Require explicit human approval before publishing tagged release artifacts instead of auto-publishing them.

Prompt for AI agents
In `pom.xml` at line 222:

**Unapproved artifacts publish publicly**

When a matching `v*` tag points to an unintended or malicious commit that passes `mvn verify`, the release workflow checks only the tag-to-POM version and `mvn verify`, then `autoPublish=true` publishes the tagged artifacts without a human approval checkpoint, so unapproved or malicious artifacts become public.

Require explicit human approval before publishing tagged release artifacts instead of auto-publishing them.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 中 · 本地部署绕过发布关卡

当维护者配置了 Central 凭据并在本地运行发布配置的部署命令时,开发者在 GitHub Actions 之外运行 mvn -P release deploy,会激活同一个发布配置并自动发布当前检出的代码,而不会执行工作流中的标签/版本检查;因此,本地构建或未打标签的构建可能会在经过审核的版本发布之前占用一个永久性的 Central 版本号。

通过仅由受保护的发布工作流设置的属性来选择启用自动发布,或者以其他方式确保每次调用都执行工作流中的发布检查。

提供给 AI 智能体的提示
在 `pom.xml` 第 222 行:

**本地部署绕过发布关卡**

当维护者配置了 Central 凭据并在本地运行发布配置的部署命令时,开发者在 GitHub Actions 之外运行 `mvn -P release deploy`,会激活同一个发布配置并自动发布当前检出的代码,而不会执行工作流中的标签/版本检查;因此,本地构建或未打标签的构建可能会在经过审核的版本发布之前占用一个永久性的 Central 版本号。

通过仅由受保护的发布工作流设置的属性来选择启用自动发布,或者以其他方式确保每次调用都执行工作流中的发布检查。
Original comment in English

🟡 Medium · Local deploy bypasses release gate

When a maintainer runs the release-profile deploy command locally with Central credentials configured, a developer running mvn -P release deploy outside GitHub Actions activates this same release profile and automatically publishes the current checkout, without the workflow’s tag/version check; a local or untagged build can therefore consume a permanent Central version before the reviewed release.

Make automatic publishing opt-in via a property set only by the guarded release workflow, or otherwise enforce the workflow’s release checks for every invocation.

Prompt for AI agents
In `pom.xml` at line 222:

**Local deploy bypasses release gate**

When a maintainer runs the release-profile deploy command locally with Central credentials configured, a developer running `mvn -P release deploy` outside GitHub Actions activates this same release profile and automatically publishes the current checkout, without the workflow’s tag/version check; a local or untagged build can therefore consume a permanent Central version before the reviewed release.

Make automatic publishing opt-in via a property set only by the guarded release workflow, or otherwise enforce the workflow’s release checks for every invocation.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟠 高 · 重新打标签会发布过时制品

当版本标签在原始发布任务仍在运行时被删除并重新指向另一个提交时,原始任务可能通过 autoPublish=true 发布其检出的提交,从而永久占用该版本号;之后,较新的运行会被拒绝,旧制品则继续公开。

当标签被重新指向时,取消正在进行的发布任务,并且只有在标签仍指向任务检出的提交时才允许上传。

另见 docs/release-guide.md:78-79。

提供给 AI 智能体的提示
在 `pom.xml` 第 222 行:

**重新打标签会发布过时制品**

当版本标签在原始发布任务仍在运行时被删除并重新指向另一个提交时,原始任务可能通过 `autoPublish=true` 发布其检出的提交,从而永久占用该版本号;之后,较新的运行会被拒绝,旧制品则继续公开。

当标签被重新指向时,取消正在进行的发布任务,并且只有在标签仍指向任务检出的提交时才允许上传。

另见 `docs/release-guide.md:78-79`。
Original comment in English

🟠 High · Retagged release publishes stale artifacts

When a version tag is deleted and repushed to a different commit while the original release job is still running, the original job can publish its checked-out commit through autoPublish=true, permanently occupying the version; the newer run is then rejected and the older artifacts remain public.

Cancel in-flight release jobs when a tag is retargeted and gate upload on the tag still pointing to the job’s checked-out commit.

Also at docs/release-guide.md:78-79.

Prompt for AI agents
In `pom.xml` at line 222:

**Retagged release publishes stale artifacts**

When a version tag is deleted and repushed to a different commit while the original release job is still running, the original job can publish its checked-out commit through `autoPublish=true`, permanently occupying the version; the newer run is then rejected and the older artifacts remain public.

Cancel in-flight release jobs when a tag is retargeted and gate upload on the tag still pointing to the job’s checked-out commit.

Also at `docs/release-guide.md:78-79`.

</configuration>
</plugin>
</plugins>
Expand Down
Loading