This is an automated email from the ASF dual-hosted git repository. jin pushed a commit to branch validate in repository https://gitbox.apache.org/repos/asf/incubator-hugegraph-doc.git
commit 37c700a31678700e7aa015efb60583159ec4171b Author: imbajin <[email protected]> AuthorDate: Sun Dec 24 00:08:32 2023 +0800 enhance the validate-release format --- .../contribution-guidelines/validate-release.md | 87 ++++++++++++--------- .../contribution-guidelines/validate-release.md | 91 ++++++++++++++-------- 2 files changed, 109 insertions(+), 69 deletions(-) diff --git a/content/cn/docs/contribution-guidelines/validate-release.md b/content/cn/docs/contribution-guidelines/validate-release.md index cae42194..935213a6 100644 --- a/content/cn/docs/contribution-guidelines/validate-release.md +++ b/content/cn/docs/contribution-guidelines/validate-release.md @@ -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 @@ -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) <[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 +.... +gpg: Total number processed: x +gpg: imported: x # 2. 信任发版用户 (你需要信任 n 个邮件里提到的 gpg 用户名, ＞1则依次执行相同操作) gpg --edit-key $USER # 这里填写具体用户名或者公钥串, 回车进入交互模式 @@ -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` 文件并且内容正常 @@ -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 @@ -140,17 +152,20 @@ 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 @@ -158,35 +173,35 @@ bin/start-hubble.sh [] -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. .... ``` - diff --git a/content/en/docs/contribution-guidelines/validate-release.md b/content/en/docs/contribution-guidelines/validate-release.md index d20bfa38..5b61a640 100644 --- a/content/en/docs/contribution-guidelines/validate-release.md +++ b/content/en/docs/contribution-guidelines/validate-release.md @@ -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 @@ -46,7 +53,10 @@ 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 @@ -54,20 +64,26 @@ 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) <[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 +... +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) @@ -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 @@ -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 @@ -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 @@ -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 @@ -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. .... ``` -
