Skip to content

Commit 0d07cef

Browse files
psxjoypsxjoy
authored
feature: enhance release verification documentation with detailed steps and compliance checks (#792)
1 parent e7546d1 commit 0d07cef

File tree

2 files changed

+386
-2
lines changed

2 files changed

+386
-2
lines changed

‎website/community/release/verify-release.md‎

Lines changed: 186 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,190 @@
22
id: 'verify-release'
33
title: 'How to Verify Release'
44
---
5+
For a detailed checklist, please refer to the official [Incubator Release Checklist](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist).
56

6-
For detailed check list, please refer to the official [check list](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist).
7+
### 1. Download the Release Candidate
8+
9+
> **Prerequisite:** Ensure you have `gpg` or `gpg2` installed.
10+
11+
:::caution Note
12+
Downloading may take some time depending on your network connection.
13+
:::
14+
15+
Set environment variables for convenience (replace with actual versions):
16+
17+
```shell
18+
# Example: export RELEASE_VERSION=0.1.0
19+
# Example: export RC_VERSION=rc1
20+
export RELEASE_VERSION={release_version}
21+
export RC_VERSION={rc_version}
22+
23+
```
24+
25+
Download the artifacts:
26+
27+
```shell
28+
# Option 1: SVN checkout (Recommended, includes KEYS file)
29+
svn co https://dist.apache.org/repos/dist/dev/incubator/fesod/${RELEASE_VERSION}-${RC_VERSION}/ fesod-dist-dev
30+
31+
# Option 2: Wget individual files
32+
wget https://dist.apache.org/repos/dist/dev/incubator/fesod/${RELEASE_VERSION}-${RC_VERSION}/apache-fesod-${RELEASE_VERSION}-src.tar.gz
33+
34+
```
35+
36+
### 2. Verify Compliance and Integrity
37+
38+
#### 2.1 Check Package Completeness
39+
40+
The uploaded artifacts must contain:
41+
42+
1. **Source Package** (Required)
43+
2. **Signature file** (.asc, Required)
44+
3. **Hash file** (.sha512, Required)
45+
46+
#### 2.2 Verify GPG Signature
47+
48+
**2.2.1 Import KEYS**
49+
50+
```shell
51+
# Download KEYS
52+
curl https://dist.apache.org/repos/dist/dev/incubator/fesod/KEYS > KEYS
53+
54+
# Import KEYS locally
55+
gpg --import KEYS
56+
57+
```
58+
59+
**2.2.2 Trust the Public Key (Optional but Recommended)**
60+
61+
```shell
62+
# Find the Key ID used for this release
63+
gpg --edit-key <KEY_ID>
64+
65+
# Type 'trust', select '5' (ultimate), confirm with 'y', then type 'quit'
66+
67+
```
68+
69+
**2.2.3 Verify the Signature**
70+
71+
```shell
72+
# Verify Source Package
73+
gpg --verify apache-fesod-${RELEASE_VERSION}-src.tar.gz.asc apache-fesod-${RELEASE_VERSION}-src.tar.gz
74+
75+
```
76+
77+
> **Success Indicator:** The output must include **`Good signature`**.
78+
79+
#### 2.3 Verify SHA512 Checksum
80+
81+
**Mac OS / Linux:**
82+
83+
```shell
84+
# Verify Source Package
85+
shasum -a 512 --check apache-fesod-${RELEASE_VERSION}-src.tar.gz.sha512
86+
87+
# Or manually compare
88+
shasum -a 512 apache-fesod-${RELEASE_VERSION}-src.tar.gz
89+
cat apache-fesod-${RELEASE_VERSION}-src.tar.gz.sha512
90+
91+
```
92+
93+
**Windows:**
94+
95+
```shell
96+
certUtil -hashfile apache-fesod-${RELEASE_VERSION}-src.tar.gz SHA512
97+
98+
```
99+
100+
### 3. Check Source Package Content (Crucial)
101+
102+
Extract the source package:
103+
104+
```shell
105+
tar -xvf apache-fesod-${RELEASE_VERSION}-src.tar.gz
106+
cd apache-fesod-${RELEASE_VERSION}-src
107+
108+
```
109+
110+
#### 3.1 Incubator Specific Checks
111+
112+
* [ ] **DISCLAIMER:** Ensure a `DISCLAIMER` (or `DISCLAIMER-WIP`) file exists in the root directory. This is mandatory for incubating projects.
113+
114+
#### 3.2 ASF License Header Check (RAT)
115+
116+
Run the Apache RAT (Release Audit Tool) check:
117+
118+
```shell
119+
# Run RAT check
120+
./mvnw apache-rat:check
121+
# Or if wrapper is not configured
122+
mvn apache-rat:check
123+
124+
```
125+
126+
**Check the report (`target/rat.txt`):**
127+
128+
* **Unapproved Licenses:** Must be **0**.
129+
* **Binaries:** Should be **0** (Source packages should not contain compiled jars/classes).
130+
131+
#### 3.3 Compilation Verification
132+
133+
Ensure the source code compiles successfully.
134+
135+
```shell
136+
# This may take time depending on network to download dependencies
137+
./mvnw clean install -DskipTests
138+
139+
```
140+
141+
**Checklist:**
142+
143+
* [ ] Build Success.
144+
* [ ] No unexpected binary files in the source tree.
145+
146+
#### 3.4 License and Notice
147+
148+
Manually check the following files in the root directory:
149+
150+
* [ ] **LICENSE:** Exists and contains the Apache License 2.0.
151+
* [ ] **NOTICE:**
152+
* Exists.
153+
* Copyright year is current (e.g., includes 2025/2026).
154+
* Contains required attributions for bundled dependencies (if any).
155+
156+
### 4. Email Reply Templates
157+
158+
After verification, reply to the vote thread on `dev@fesod.apache.org`.
159+
160+
:::tip
161+
As a **PPMC member**, your vote is **binding**. Please include `(binding)` in your reply.
162+
:::
163+
164+
**Template for PPMC Members:**
165+
166+
```text
167+
+1 (binding)
168+
169+
[X] Download links are valid.
170+
[X] Checksums and signatures.
171+
[X] LICENSE/NOTICE files exist
172+
[X] No unexpected binary files
173+
[X] All source files have ASF headers
174+
[X] Can compile from source
175+
176+
My Environment:
177+
- OS: MacOS <Version> / Linux
178+
- JDK: <JDK Version>
179+
- Maven: <Maven Version>
180+
181+
```
182+
183+
**Template for Contributors (Non-PPMC):**
184+
185+
```text
186+
+1 (non-binding)
187+
188+
I have checked:
189+
... (Same as above)
190+
191+
```

‎website/i18n/zh-cn/docusaurus-plugin-content-docs-community/current/release/verify-release.md‎

Lines changed: 200 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,203 @@ id: 'verify-release'
33
title: '如何验证版本'
44
---
55

6-
如需查看详细检查清单，请访问官方的[检查清单](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist)页面。
6+
详细检查列表请参考官方的 [Incubator Release Checklist](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist)。
7+
8+
### 1. 下载要发布的候选版本
9+
10+
> 验证环节需依赖 GPG 工具，建议预先安装 `gpg` 或 `gpg2`。
11+
12+
:::caution 注意
13+
请确保网络环境畅通，下载耗时取决于网络状况。
14+
:::
15+
16+
首先，设置环境变量以便于后续命令执行（请替换为实际的版本号）：
17+
18+
```shell
19+
# 例如：export RELEASE_VERSION=0.1.0
20+
# 例如：export RC_VERSION=rc1
21+
export RELEASE_VERSION={发布版本号}
22+
export RC_VERSION={RC版本号}
23+
24+
```
25+
26+
下载物料：
27+
28+
```shell
29+
# 方式一：如果本地有 SVN，直接 checkout (推荐，包含了 KEYS 文件)
30+
svn co https://dist.apache.org/repos/dist/dev/incubator/fesod/${RELEASE_VERSION}-${RC_VERSION}/ fesod-dist-dev
31+
32+
# 方式二：使用 wget 直接下载特定文件
33+
wget https://dist.apache.org/repos/dist/dev/incubator/fesod/${RELEASE_VERSION}-${RC_VERSION}/apache-fesod-${RELEASE_VERSION}-src.tar.gz
34+
35+
```
36+
37+
### 2. 验证上传的版本是否合规
38+
39+
#### 2.1 检查发布包完整性
40+
41+
上传到 dist 的包必须包含：
42+
43+
1. **源码包** (Source Package, 必须)
44+
2. **签名文件** (.asc, 必须)
45+
3. **哈希文件** (.sha512, 必须)
46+
47+
#### 2.2 检查 GPG 签名
48+
49+
首先导入发布人的公钥。
50+
51+
**2.2.1 导入 KEYS**
52+
53+
```shell
54+
# 从 SVN 仓库下载 KEYS (通常在版本目录或根目录)
55+
curl https://dist.apache.org/repos/dist/dev/incubator/fesod/KEYS > KEYS
56+
57+
# 导入 KEYS 到本地
58+
gpg --import KEYS
59+
60+
```
61+
62+
**2.2.2 信任公钥 (可选，但推荐)**
63+
64+
```shell
65+
# 查找本次发版人的 Key ID，并进行信任设置
66+
gpg --edit-key <KEY_ID>
67+
68+
# 输入 trust，选择 5 (ultimate)，确认 y，最后 quit
69+
70+
```
71+
72+
**2.2.3 验证签名**
73+
74+
```shell
75+
# 验证源码包
76+
gpg --verify apache-fesod-${RELEASE_VERSION}-src.tar.gz.asc apache-fesod-${RELEASE_VERSION}-src.tar.gz
77+
```
78+
79+
> **检查结果：** 必须出现 **`Good signature`** 字样。
80+
81+
#### 2.3 检查 SHA512 哈希
82+
83+
**Mac OS / Linux:**
84+
85+
```shell
86+
# 验证源码包
87+
shasum -a 512 --check apache-fesod-${RELEASE_VERSION}-src.tar.gz.sha512
88+
89+
# 或者手动对比
90+
shasum -a 512 apache-fesod-${RELEASE_VERSION}-src.tar.gz
91+
# 查看 .sha512 文件内容进行肉眼比对
92+
cat apache-fesod-${RELEASE_VERSION}-src.tar.gz.sha512
93+
94+
```
95+
96+
**Windows:**
97+
98+
```shell
99+
certUtil -hashfile apache-fesod-${RELEASE_VERSION}-src.tar.gz SHA512
100+
101+
```
102+
103+
### 3. 检查源码包内容 (核心合规项)
104+
105+
解压源码包：
106+
107+
```shell
108+
tar -xvf apache-fesod-${RELEASE_VERSION}-src.tar.gz
109+
cd apache-fesod-${RELEASE_VERSION}-src
110+
111+
```
112+
113+
#### 3.1 孵化器特有检查 (Incubator Check)
114+
115+
作为孵化项目，必须检查根目录下是否存在 `DISCLAIMER` (或 `DISCLAIMER-WIP`) 文件。
116+
117+
* **检查项：** 确认存在 `DISCLAIMER` 文件，且内容声明了这是一个处于孵化阶段的项目。
118+
119+
#### 3.2 ASF License Header (RAT 检查)
120+
121+
使用 Maven 插件进行 License 头检查。
122+
123+
```shell
124+
# 运行 RAT 检查
125+
./mvnw apache-rat:check
126+
# 或者如果未配置 wrapper
127+
mvn apache-rat:check
128+
129+
```
130+
131+
**检查结果分析：**
132+
查看生成的报告文件（通常在 `target/rat.txt` 或控制台输出）：
133+
134+
* **Unapproved Licenses:** 必须为 0。
135+
* **Binaries:** 应当为 0 (源码包中不应包含编译后的二进制 jar/class 文件)。
136+
137+
```shell
138+
# 快速查看异常文件 (Mac/Linux)
139+
find . -name rat.txt -print0 | xargs -0 -I file cat file | grep "Unapproved Licenses"
140+
141+
```
142+
143+
#### 3.3 源码编译验证
144+
145+
确保源码可以被正确编译打包。
146+
147+
```shell
148+
# 首次编译可能需要下载依赖，耗时视网络而定
149+
./mvnw clean install -DskipTests
150+
151+
```
152+
153+
**检查项：**
154+
155+
* [ ] Build Success (编译成功)
156+
* [ ] 源码包中**不包含**任何非必要的二进制文件 (如 `.jar`, `.zip`, `.class`)。
157+
158+
#### 3.4 许可证合规性检查
159+
160+
进入解压后的目录，人工检查：
161+
162+
* [ ] **LICENSE 文件：** 存在且内容标准 (Apache License 2.0)。
163+
* [ ] **NOTICE 文件：**
164+
* 存在。
165+
* 年份正确 (例如包含 2025/2026)。
166+
* 如果引入了其他必须在 NOTICE 中声明的依赖，需确认已包含。
167+
168+
* [ ] **DISCLAIMER 文件：** 存在（孵化项目必须）。
169+
170+
### 4. 邮件回复示例
171+
172+
验证完成后，请在开发者邮件列表 (`dev@fesod.apache.org`) 回复投票邮件。
173+
174+
:::tip 特别提示
175+
你是 **PPMC 成员**，你的投票是 **Binding (有约束力)** 的。请务必带上 `(binding)` 后缀。
176+
:::
177+
178+
**回复模板 (PPMC 成员):**
179+
180+
```text
181+
+1 (binding)
182+
183+
[X] Download links are valid.
184+
[X] Checksums and signatures.
185+
[X] LICENSE/NOTICE files exist
186+
[X] No unexpected binary files
187+
[X] All source files have ASF headers
188+
[X] Can compile from source
189+
190+
My Environment:
191+
- OS: MacOS <版本号> / Linux
192+
- JDK: <JDK版本>
193+
- Maven: <Maven版本>
194+
195+
```
196+
197+
**回复模板 (非 PPMC 成员/贡献者):**
198+
199+
```text
200+
+1 (non-binding)
201+
202+
I have checked:
203+
... (同上)
204+
205+
```

0 commit comments

Comments
 (0)