Skip to content

Commit

Permalink
enhance validate release doc (#167)
Browse files Browse the repository at this point in the history 
Co-authored-by: imbajin <[email protected]>
  • Loading branch information
@z7658329 @imbajin
z7658329 and imbajin committed Dec 31, 2022
1 parent 27eaddb commit 26a13de
Show file tree
Hide file tree
Showing 2 changed files with 127 additions and 31 deletions.
84 changes: 66 additions & 18 deletions content/cn/docs/contribution-guidelines/validate-release.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,33 +8,82 @@ weight: 3

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

#### 1. 检查 hash 值
#### 1. 准备工作

首先需要检查 `source + binary` 包的文件完整性, 通过 `shasum` 进行校验, 确保和发布到 apache/github 上的 hash 值一致 (一般是 sha512), 这里同0x02的最后一步检验.
如果本地没有 svn 或 gpg 环境, 建议先安装一下 (windows 推荐使用 WSL2 环境, 或者至少是 `git-bash`)

#### 2. 检查 gpg 签名
```bash
# 1. 安装svn
# ubuntu/debian
sudo apt install subversion -y
# MacOS
brew install subversion
# 验证安装是否成功, 执行以下命令:
svn --version

# 2. 安装gpg
# ubuntu/debian
sudo apt-get install gnupg -y
# MacOS
brew install gnupg
# 验证安装是否成功, 执行以下命令:
gpg --version

# 3. 下载 hugegraph-svn 目录 (版本号注意填写此次验证版本, 这里以1.0.0为例)
svn co https://dist.apache.org/repos/dist/dev/incubator/hugegraph/1.0.0/
# (注) 如果出现 svn 下载某个文件速度很慢的情况, 可以考虑 wget 单个文件下载, 如下 (或考虑使用代理)
wget https://dist.apache.org/repos/dist/dev/incubator/hugegraph/1.0.0/apache-hugegraph-toolchain-incubating-1.0.0.tar.gz
```

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

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

```bash
# 1. 下载项目可信赖公钥到本地 (首次需要)
curl xxx >> PK
gpg --import PK
# 1.2 等待响应后输入 trust 表示信任 tom 的公钥 (其他人名类似)
gpg -edit-key tom
执行命令:
for i in *.tar.gz; do echo $i; shasum -a 512 --check $i.sha512; done
```
#### 3. 检查 gpg 签名

# 2. 检查签名 (可用 0x03 章节的第 ⑧ 步的 for 循环脚本批量遍历)
这个就是为了确保发布的包是由**可信赖**的人上传的, 假设 tom 签名后上传, 其他人应该下载 A 的**公钥**然后进行**签名确认**, 相关命令:

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

# 导入后可以看到如下输出, 这代表导入了 3 个用户公钥
gpg: /home/ubuntu/.gnupg/trustdb.gpg: trustdb created
gpg: key B78B058CC255F6DC: public key "Imba Jin (apache mail) <[email protected]>" imported
gpg: key 818108E7924549CC: public key "vaughn <[email protected]>" imported
gpg: key 28DCAED849C4180E: public key "coderzc (CODE SIGNING KEY) <[email protected]>" imported
gpg: Total number processed: 3
gpg: imported: 3

# 2. 信任发版用户 (这里需要信任 3 个, 对 Imba Jin, vaughn, coderzc 依次执行相同操作)
gpg --edit-key Imba Jin # 以第一个为例, 进入交互模式
gpg> trust
...输出选项..
Your decision? 5 #选择5
Do you really want to set this key to ultimate trust? (y/N) y #选择y, 然后 q 退出信任下一个用户


# 3. 检查签名(确保没有 Warning 输出, 每一个 source/binary 文件都提示 Good Signature)
#单个文件验证
gpg --verify xx.asc xxx-source.tar.gz
gpg --verify xx.asc xxx-binary.tar.gz # 注: 我们目前没有 binary 后缀
#for循环遍历验证(推荐使用)
for i in *.tar.gz; do echo $i; gpg --verify $i.asc $i ; done

```

先确认了整体的完整性/一致性, 然后接下来确认具体的内容 (**关键**)
先确认了整体的"完整性 + 一致性", 然后接下来确认具体的内容 (**关键**)

#### 3. 检查压缩包内容
#### 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` 地址下载包到本地 (地址: `dist.apache.org/repos/dist/dev/hugegraph/`)
首先我们需要从 apache 官方的 `release-candidate` 地址下载包到本地 (地址: [点击跳转](https://dist.apache.org/repos/dist/dev/incubator/hugegraph/))

##### A. 源码包

Expand All @@ -51,7 +100,7 @@ gpg --verify xx.asc xxx-binary.tar.gz # 注: 我们目前没有 binary 后缀

```bash
# 同时也可以检查一下代码风格是否符合规范, 不符合的可以放下一次调整
mvn clean test -Dcheckstyle.skip=false
mvn clean package -Dmaven.test.skip=true -Dcheckstyle.skip=false
```

##### B. 二进制包
Expand All @@ -60,12 +109,11 @@ mvn clean test -Dcheckstyle.skip=false

1. 文件夹都带有 `incubating`
2. 存在 `LICENSE` + `NOTICE` 文件并且内容正常
3. 通过 gpg 命令确认每个文件的签名正常

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

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

1. 确保官网至少满足 [apache website check](https://whimsy.apache.org/pods/project/hugegraph), 以及没有死链等
2. 更新**下载链接**以及版本更新说明
3. …..
3. ...
74 changes: 61 additions & 13 deletions content/en/docs/contribution-guidelines/validate-release.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,33 +10,81 @@ weight: 3

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. check hash value
#### 1. prepare

If there is no svn or gpg environment locally, it is recommended to install it first (windows recommend using WSL2 environment, or at least `git-bash`)
```bash
# 1. install svn
# ubuntu/debian
sudo apt install subversion -y
# MacOS
brew install subversion
# To verify that the installation was successful, execute the following command:
svn --version

# 2. install gpg
# ubuntu/debian
sudo apt-get install gnupg -y
# MacOS
brew install gnupg
# To verify that the installation was successful, execute the following command:
gpg --version

# 3. Download the hugegraph-svn directory (version number, pay attention to fill in the verification version, here we take 1.0.0 as an example)
svn co https://dist.apache.org/repos/dist/dev/incubator/hugegraph/1.0.0/
# (Note) If svn downloads a file very slowly, you can consider wget to download a single file, as follows (or consider using a proxy)
wget https://dist.apache.org/repos/dist/dev/incubator/hugegraph/1.0.0/apache-hugegraph-toolchain-incubating-1.0.0.tar.gz
```

#### 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.
```bash
execute the following command:
for i in *.tar.gz; do echo $i; shasum -a 512 --check $i.sha512; done
```

#### 2. check gpg signature
#### 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:

```bash
# 1. Download the trusted public key of the project to the local (required for the first time)
curl xxx >> PK
gpg --import PK
# 1.2 Enter trust after waiting for the response to trust Tom's public key (other names are similar)
gpg -edit-key tom

# 2. Check the signature (you can use the for loop script in step ⑧ of Chapter 0x03 to traverse in batches)
# 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
gpg: /home/ubuntu/.gnupg/trustdb.gpg: trustdb created
gpg: key B78B058CC255F6DC: public key "Imba Jin (apache mail) <[email protected]>" imported
gpg: key 818108E7924549CC: public key "vaughn <[email protected]>" imported
gpg: key 28DCAED849C4180E: public key "coderzc (CODE SIGNING KEY) <[email protected]>" imported
gpg: Total number processed: 3
gpg: imported: 3

# 2. Trust release users (here you need to trust 3 users, perform the same operation for Imba Jin, vaughn, coderzc in turn)
gpg --edit-key Imba Jin # Take the first one as an example, enter the interactive mode
gpg> trust
...output options..
Your decision? 5 #select five
Do you really want to set this key to ultimate trust? (y/N) y #slect y, then q quits trusting the next user


# 3. Check the signature (make sure there is no Warning output, every source/binary file prompts Good Signature)
#Single file verification
gpg --verify xx.asc xxx-source.tar.gz
gpg --verify xx.asc xxx-binary.tar.gz # Note: We currently do not have a binary suffix
gpg --verify xx.asc xxx-binary.tar.gz # 注: 我们目前没有 binary 后缀
#for loop traversal verification (recommended)
for i in *.tar.gz; do echo $i; gpg --verify $i.asc $i ; done

```

First confirm the overall integrity/consistency, and then confirm the specific content (**key**)

#### 3. Check the archive contents
#### 4. Check the archive contents

Here it is divided into two aspects: source code package + binary package, The source code package is more strict, 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: `dist.apache.org/repos/dist/dev/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 Down Expand Up @@ -66,7 +114,7 @@ After decompressing `xxx-hugegraph.tar.gz`, perform the following checks:

**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

#### 4. Check the official website and github and other pages
#### 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.
2. Update **download link** and version update instructions
Expand Down

0 comments on commit 26a13de

Please sign in to comment.