Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

refact: enhance the validate-release format #315

Merged
merged 1 commit into from
Dec 23, 2023
Merged

refact: enhance the validate-release format #315

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
87 changes: 51 additions & 36 deletions content/cn/docs/contribution-guidelines/validate-release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,15 @@ weight: 3

## 验证阶段

当内部的临时发布和打包工作完成后, 其他的社区开发者(尤其是 PMC)需要参与到[验证环节](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist)确保某个人发布版本的"正确性 + 完整性", 这里需要**每个人**都尽量参与, 然后后序**邮件回复**的时候说明自己**已检查**了哪些项. (下面是核心项)
当内部的临时发布和打包工作完成后，其他的社区开发者 (尤其是 PMC)
需要参与到[验证环节](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist)
确保某个人发布版本的"正确性 + 完整性", 这里需要**每个人**都尽量参与，然后后序**邮件回复**的时候说明自己
**已检查**了哪些项。(下面是核心项)

#### 1. 准备工作

如果本地没有 svn 或 gpg 或 wget 环境, 建议先安装一下 (windows 推荐使用 WSL2 环境, 或者至少是 `git-bash`), 同时确保安装Java(推荐11)和maven软件。
如果本地没有 svn 或 gpg 或 wget 环境，建议先安装一下 (windows 推荐使用 WSL2 环境，
或者至少是 `git-bash`), 同时确保安装 Java(推荐 11) 和 maven 软件。

```bash
# 1. 安装svn
Expand Down Expand Up @@ -45,28 +49,32 @@ wget https://dist.apache.org/repos/dist/dev/incubator/hugegraph/1.x.x/apache-hug

#### 2. 检查 hash 值

首先需要检查 `source + binary` 包的文件完整性, 通过 `shasum` 进行校验, 确保和发布到 apache/github 上的 hash 值一致 (一般是 sha512)
首先需要检查 `source + binary` 包的文件完整性，通过 `shasum` 进行校验，确保和发布到 apache/github 上的
hash 值一致 (一般是 sha512)

```bash
执行命令:
for i in *.tar.gz; do echo $i; shasum -a 512 --check $i.sha512; done
```

#### 3. 检查 gpg 签名

这个就是为了确保发布的包是由**可信赖**的人上传的, 假设 tom 签名后上传, 其他人应该下载 A 的**公钥**然后进行**签名确认**, 相关命令:
这个就是为了确保发布的包是由**可信赖**的人上传的，假设 tom 签名后上传，其他人应该下载 A 的**公钥**
然后进行**签名确认**, 相关命令：

```bash
# 1. 下载项目可信赖公钥到本地 (首次需要) & 导入
curl https://downloads.apache.org/incubator/hugegraph/KEYS > KEYS
gpg --import KEYS

# 导入后可以看到如下输出, 这代表导入了 3 个用户公钥
# 导入后可以看到如下输出, 这代表导入了 x 个用户公钥
gpg: /home/ubuntu/.gnupg/trustdb.gpg: trustdb created
gpg: key BA7E78F8A81A885E: public key "imbajin (apache mail) <jin@apache.org>" imported
gpg: key 818108E7924549CC: public key "vaughn <vaughn@apache.org>" imported
gpg: key 28DCAED849C4180E: public key "coderzc (CODE SIGNING KEY) <zhaocong@apache.org>" imported
gpg: Total number processed: 3
gpg: imported: 3
....
gpg: Total number processed: x
gpg: imported: x

# 2. 信任发版用户 (你需要信任 n 个邮件里提到的 gpg 用户名, ＞1则依次执行相同操作)
gpg --edit-key $USER # 这里填写具体用户名或者公钥串, 回车进入交互模式
Expand Down Expand Up @@ -95,13 +103,15 @@ for i in *.tar.gz; do echo $i; gpg --verify $i.asc $i ; done

#### 4. 检查压缩包内容

这里分源码包 + 二进制包两个方面, 源码包更为严格, 挑核心的部分说 (完整的列表可参考官方 [Wiki](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist), 比较长)
这里分源码包 + 二进制包两个方面，源码包更为严格，挑核心的部分说
(完整的列表可参考官方 [Wiki](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist), 比较长)

首先我们需要从 apache 官方的 `release-candidate` 地址下载包到本地 (地址: [点击跳转](https://dist.apache.org/repos/dist/dev/incubator/hugegraph/))
首先我们需要从 apache 官方的 `release-candidate` 地址下载包到本地 (
地址：[点击跳转](https://dist.apache.org/repos/dist/dev/incubator/hugegraph/))

##### A. 源码包

解压 `*hugegraph*src.tar.gz`后, 进行如下检查:
解压 `*hugegraph*src.tar.gz`后，进行如下检查：

1. 文件夹都带有 `incubating`, 且不存在**空的**文件/文件夹
2. 存在 `LICENSE` + `NOTICE` + 存在 `DISCLAIMER` 文件并且内容正常
Expand All @@ -110,23 +120,25 @@ for i in *.tar.gz; do echo $i; gpg --verify $i.asc $i ; done
5. 检查每个父 / 子模块的 `pom.xml` 版本号是否一致 (且符合期望)
6. 最后，确保源码可以正常 / 正确编译 (然后看看测试和规范)

PMC 同学请特别注意认真检查 `LICENSE` + `NOTICE` 文件, 确保文件严格遵循了 ASF 的发版要求, 大部分的发版问题都与之相关
PMC 同学请特别注意认真检查 `LICENSE` + `NOTICE` 文件，确保文件严格遵循了 ASF 的发版要求，
大部分的发版问题都与之相关

```bash
# 请优先使用/切换到 java 11 版本进行后序的编译和运行操作
# java --version

# 尝试在 Unix 环境下编译测试是否正常
mvn clean package -Dmaven.test.skip=true -Dcheckstyle.skip=true
# 尝试在 Unix 环境下编译测试是否正常 (stage 表示从 stage 仓库拉取依赖)
mvn clean package -P stage -Dmaven.test.skip=true -Dcheckstyle.skip=true
```

##### B. 二进制包

解压 `xxx-hugegraph.tar.gz`后, 进行如下检查:
解压 `xxx-hugegraph.tar.gz`后，进行如下检查：

1. 文件夹都带有 `incubating`
2. 存在 `LICENSE` + `NOTICE` 文件并且内容正常
3. 服务启动

```bash
# hugegraph-server
bin/start-hugegraph.sh
Expand All @@ -140,53 +152,56 @@ bin/start-hubble.sh
更多参考官网: https://hugegraph.apache.org/cn/docs/quickstart
```

**注:** 如果二进制包里面引入了第三方依赖, 则需要更新 LICENSE, 加入第三方依赖的 LICENSE; 若第三方依赖 LICENSE 是 Apache 2.0, 且对应的项目中包含了 NOTICE, 则还需要更新我们的 NOTICE 文件
**注:** 如果二进制包里面引入了第三方依赖, 则需要更新 LICENSE, 加入第三方依赖的 LICENSE; 若第三方依赖
LICENSE 是 Apache 2.0, 且对应的项目中包含了 NOTICE, 则还需要更新我们的 NOTICE 文件

#### 5. 检查官网以及 github 等页面

1. 确保官网至少满足 [apache website check](https://whimsy.apache.org/pods/project/hugegraph), 以及没有死链等
2. 更新**下载链接**存在, 以及版本更新说明页面更新
1. 确保官网至少满足 [apache website check](https://whimsy.apache.org/pods/project/hugegraph),
以及没有死链等
2. 更新**下载链接**存在，以及版本更新说明页面更新
3. ...

## 邮件模板

检查完成后, 你应该按不同角色回复邮件: (普通开发者 & PMC 成员)
检查完成后，你应该按不同角色回复邮件：(普通开发者 & PMC 成员)

```markdown
[] +1 approve

[] +0 no opinion

[] -1 disapprove with the reason
```

```markdown
+1 (non-binding)
I checked:
1.Download link/tag in mail are valid
2.Checksum and GPG signatures are OK
3.LICENSE & NOTICE & DISCLAIMER are exist
4.Build successfully on XX OS version XXX
5.No unexpected binary files
6.Date is right in the NOTICE file
7.Compile from source is fine under JavaX
8.No empty file & directory found
1. Download link/tag in mail are valid
2. Checksum and GPG signatures are OK
3. LICENSE & NOTICE & DISCLAIMER are exist
4. Build successfully on XX OS version XXX
5. No unexpected binary files
6. Date is right in the NOTICE file
7. Compile from source is fine under JavaX
8. No empty file & directory found
9. Test running xxx service OK
10. ....
```

特别注意 PMC 成员必须使用 `binding` 标记回复邮件, 这对于统计有效投票很重要;
特别注意 PMC 成员必须使用 `binding` 标记回复邮件，这对于统计有效投票很重要;

```markdown
+1 (binding)
I checked:
1.Download link/tag in mail are valid
2.Checksum and GPG signatures are OK
3.LICENSE & NOTICE & DISCLAIMER are exist
4.Build successfully on XX OS Version XX
5.No unexpected binary files
6.Date is right in the NOTICE file
7.Compile from source is fine under JavaXX
8.No empty file & directory found
1. Download link/tag in mail are valid
2. Checksum and GPG signatures are OK
3. LICENSE & NOTICE & DISCLAIMER are exist
4. Build successfully on XX OS Version XX
5. No unexpected binary files
6. Date is right in the NOTICE file
7. Compile from source is fine under JavaXX
8. No empty file & directory found
9. Test running XXX service OK
10. ....
```

91 changes: 58 additions & 33 deletions content/en/docs/contribution-guidelines/validate-release.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,18 @@ weight: 3

## Verification

When the internal temporary release and packaging work is completed, other community developers (especially PMC) need to participate in the [verification link](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist)To ensure the "correctness + completeness" of someone's published version, here requires **everyone** to participate as much as possible, and then explain which items you have **checked** in the subsequent **email reply**. (The following are the core items)
When the internal temporary release and packaging work is completed, other community developers (
especially PMC) need to participate in the [verification link](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist)
To ensure the "correctness + completeness" of someone's published version, here requires **everyone
** to participate as much as possible, and then explain which items you have **checked** in the
subsequent **email reply**.(The following are the core items)

#### 1. prepare

If there is no svn or gpg or wget environment locally, it is recommended to install it first (windows recommend using WSL2 environment, or at least `git-bash`), also make sure to install java (recommended 11) and maven software
If there is no svn or gpg or wget environment locally, it is recommended to install it first
(windows recommend using WSL2 environment, or at least `git-bash`), also make sure to install java
(recommended 11) and maven software

```bash
# 1. install svn
# ubuntu/debian
Expand Down Expand Up @@ -46,28 +53,37 @@ wget https://dist.apache.org/repos/dist/dev/incubator/hugegraph/1.x.x/apache-hug

#### 2. check hash value

First you need to check the file integrity of the `source + binary` package, Verify by `shasum` to ensure that it is consistent with the hash value published on apache/github (Usually sha512), Here is the same as the last step of 0x02 inspection.
First you need to check the file integrity of the `source + binary` package, Verify by `shasum` to
ensure that it is consistent with the hash value published on apache/GitHub (Usually sha512), Here
is the same as the last step of 0x02 inspection.

```bash
execute the following command:
for i in *.tar.gz; do echo $i; shasum -a 512 --check $i.sha512; done
```

#### 3. check gpg signature

This is to ensure that the published package is uploaded by a **reliable** person. Assuming tom signs and uploads, others should download A’s **public key** and then perform **signature confirmation**. Related commands:
This is to ensure that the published package is uploaded by a **reliable** person.
Assuming tom signs and uploads,
others should download A's **public key** and then perform **signature
confirmation**.

Related commands:

```bash
# 1. Download project trusted public key to local (required for the first time) & import
curl https://downloads.apache.org/incubator/hugegraph/KEYS > KEYS
gpg --import KEYS

# After importing, you can see the following output, which means that 3 user public keys have been imported
# After importing, you can see the following output, which means that x user public keys have been imported
gpg: /home/ubuntu/.gnupg/trustdb.gpg: trustdb created
gpg: key BA7E78F8A81A885E: public key "imbajin (apache mail) <jin@apache.org>" imported
gpg: key 818108E7924549CC: public key "vaughn <vaughn@apache.org>" imported
gpg: key 28DCAED849C4180E: public key "coderzc (CODE SIGNING KEY) <zhaocong@apache.org>" imported
gpg: Total number processed: 3
gpg: imported: 3
...
gpg: Total number processed: x
gpg: imported: x

# 2. Trust release users (trust n username mentioned in voting mail, if more than one user,
# just repeat the steps in turn or use the script below)
Expand Down Expand Up @@ -99,9 +115,12 @@ First confirm the overall integrity/consistency, and then confirm the specific c

#### 4. Check the archive contents

Here it is divided into two aspects: source code package + binary package, The source code package is stricter, it can be said that the core part (Because it is longer,For a complete list refer to the official [Wiki](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist))
Here it is divided into two aspects: source code package + binary package, The source code package
is stricter, it can be said that the core part (Because it is longer, For a complete list refer to
the official [Wiki](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist))

First of all, we need to download the package from the apache official `release-candidate` URL to the local (URL: [click to jump](https://dist.apache.org/repos/dist/dev/incubator/hugegraph/))
First of all, we need to download the package from the apache official `release-candidate` URL to
the local (URL: [click to jump](https://dist.apache.org/repos/dist/dev/incubator/hugegraph/))

##### A. source package

Expand All @@ -110,16 +129,18 @@ After decompressing `*hugegraph*src.tar.gz`, Do the following checks:
1. folders with `incubating`, and no **empty** files/folders
2. `LICENSE` + `NOTICE` + `DISCLAIM` file exists and the content is normal
3. **does not exist** binaries (without LICENSE)
4. The source code files all contain the standard `ASF License` header (this could be done with the `Maven-MAT` plugin)
5. Check whether the `pom.xml` version number of each parent/child module is consistent (and meet expectations)
4. The source code files all contain the standard `ASF License` header (this could be done with
the `Maven-MAT` plugin)
5. Check whether the `pom.xml` version number of each parent/child module is consistent (and meet
expectations)
6. Finally, make sure the source code works/compiles correctly

```bash
# prefer to use/switch to java 11 for the following operations (compiling/running)
# java --version

# try to test in the Unix env to check if it works well
mvn clean package -Dmaven.test.skip=true -Dcheckstyle.skip=true
# try to compile in the Unix env to check if it works well
mvn clean package -P stage -Dmaven.test.skip=true -Dcheckstyle.skip=true
```

##### B. binary package
Expand All @@ -129,6 +150,7 @@ After decompressing `xxx-hugegraph.tar.gz`, perform the following checks:
1. folders with `incubating`
2. `LICENSE` and `NOTICE` file exists and the content is normal
3. start server

```bash
# hugegraph-server
bin/start-hugegraph.sh
Expand All @@ -142,17 +164,20 @@ bin/start-hubble.sh
more reference official website: https://hugegraph.apache.org/docs/quickstart
```

**Note:** If a third-party dependency is introduced in the binary package, you need to update the LICENSE and add the third-party dependent LICENSE; if the third-party dependent LICENSE is Apache 2.0, and the corresponding project contains NOTICE, you also need to update Our NOTICE file
**Note:** If a third-party dependency is introduced in the binary package, you need to update the
LICENSE and add the third-party dependent LICENSE; if the third-party dependent LICENSE is Apache
2.0, and the corresponding project contains NOTICE, you also need to update Our NOTICE file

#### 5. Check the official website and GitHub and other pages

1. Make sure that the official website at least meets [apache website check](https://whimsy.apache.org/pods/project/hugegraph), and no circular links etc.
1. Make sure that the official website at least meets [apache website check](https://whimsy.apache.org/pods/project/hugegraph),
and no circular links, etc.
2. Update **download link** and release notes updated
3. ...

## Mail Template

After the check & test, you should reply the mail with the following content: (normal devs & PMC)
After the check & test, you should reply to the mail with the following content: (normal devs & PMC)

```markdown
[] +1 approve
Expand All @@ -165,31 +190,31 @@ After the check & test, you should reply the mail with the following content: (n
```markdown
+1 (non-binding)
I checked:
1.Download link/tag in mail are valid
2.Checksum and GPG signatures are OK
3.LICENSE & NOTICE & DISCLAIMER are exist
4.Build successfully on XX OS & Version XX
5.No unexpected binary files
6.Date is right in the NOTICE file
7.Compile from source is fine under JavaXX
8.No empty file & directory found
1. Download link/tag in mail are valid
2. Checksum and GPG signatures are OK
3. LICENSE & NOTICE & DISCLAIMER are exist
4. Build successfully on XX OS & Version XX
5. No unexpected binary files
6. Date is right in the NOTICE file
7. Compile from source is fine under JavaXX
8. No empty file & directory found
9. Test running XXX service OK
10. ....
```

and the PMC members should reply with `binding`, it's important for summary the valid votes:

```markdown
+1 (binding)
I checked:
1.Download link/tag in mail are valid
2.Checksum and GPG signatures are OK
3.LICENSE & NOTICE & DISCLAIMER are exist
4.Build successfully on XX OS & Version XX
5.No unexpected binary files
6.Date is right in the NOTICE file
7.Compile from source is fine under JavaXX
8.No empty file & directory found
1. Download link/tag in mail are valid
2. Checksum and GPG signatures are OK
3. LICENSE & NOTICE & DISCLAIMER are exist
4. Build successfully on XX OS & Version XX
5. No unexpected binary files
6. Date is right in the NOTICE file
7. Compile from source is fine under JavaXX
8. No empty file & directory found
9. Test running XX process OK
10. ....
```