From 3ec04b09228d5203d883ef49f2d5893bddf2ddb4 Mon Sep 17 00:00:00 2001 From: imbajin Date: Fri, 30 Dec 2022 19:36:31 +0800 Subject: [PATCH] release: add apache 1.0.0 doc & how to validate (#162) --- content/cn/contribution-guidelines/_index.md | 5 + .../cn/contribution-guidelines/contribute.md | 169 ++++++++++++++++++ .../cn/contribution-guidelines/subscribe.md | 29 +++ .../validate-release.md | 71 ++++++++ .../hugegraph-1.0.0-release-notes.md | 56 ++++++ .../hugegraph-1.0.0-release-notes.md | 54 ++++++ .../en/docs/contribution-guidelines/_index.md | 2 +- .../validate-release.md | 73 ++++++++ 8 files changed, 458 insertions(+), 1 deletion(-) create mode 100755 content/cn/contribution-guidelines/_index.md create mode 100644 content/cn/contribution-guidelines/contribute.md create mode 100644 content/cn/contribution-guidelines/subscribe.md create mode 100644 content/cn/contribution-guidelines/validate-release.md create mode 100644 content/cn/docs/changelog/hugegraph-1.0.0-release-notes.md create mode 100644 content/en/docs/changelog/hugegraph-1.0.0-release-notes.md create mode 100644 content/en/docs/contribution-guidelines/validate-release.md diff --git a/content/cn/contribution-guidelines/_index.md b/content/cn/contribution-guidelines/_index.md new file mode 100755 index 000000000..2cdf8103d --- /dev/null +++ b/content/cn/contribution-guidelines/_index.md @@ -0,0 +1,5 @@ +--- +title: "Contribution Guidelines" +linkTitle: "Contribution Guidelines" +weight: 9 +--- diff --git a/content/cn/contribution-guidelines/contribute.md b/content/cn/contribution-guidelines/contribute.md new file mode 100644 index 000000000..50a90adf9 --- /dev/null +++ b/content/cn/contribution-guidelines/contribute.md @@ -0,0 +1,169 @@ +--- +title: "如何参与 HugeGraph 社区" +linkTitle: "如何参与 HugeGraph 社区" +weight: 1 +--- + +> TODO: translate this article to Chinese + +Thanks for taking the time to contribute! As an open source project, HugeGraph is looking forward to be contributed from everyone, and we are also grateful to all the contributors. + +The following is a contribution guide for HugeGraph: + +image + +## 1. Preparation + +We can contribute by reporting issues, submitting code patches or any other feedback. + +Before submitting the code, we need to do some preparation: + +1. Sign up or login to GitHub: [https://github.com](https://github.com) + +2. Fork HugeGraph repo from GitHub: [https://github.com/apache/incubator-hugegraph/fork](https://github.com/hugegraph/hugegraph/fork) + +3. Clone code from fork repo to local: [https://github.com/${GITHUB_USER_NAME}/hugegraph](https://github.com/${GITHUB_USER_NAME}/hugegraph) + + ```shell + # clone code from remote to local repo + git clone https://github.com/${GITHUB_USER_NAME}/hugegraph + ``` + +4. Configure local HugeGraph repo + + ```shell + cd hugegraph + + # add upstream to synchronize the latest code + git remote add hugegraph https://github.com/hugegraph/hugegraph + + # set name and email to push code to github + git config user.name "{full-name}" # like "Jermy Li" + git config user.email "{email-address-of-github}" # like "jermy@apache.org" + ``` + +Optional: You can use [GitHub desktop](https://desktop.github.com/) to greatly simplify the commit and update process. + +## 2. Create an Issue on GitHub + +If you encounter bugs or have any questions, please go to [GitHub Issues](https://github.com/apache/incubator-hugegraph/issues) to report them and feel free to [create an issue](https://github.com/hugegraph/hugegraph/issues/new). + +## 3. Make changes of code locally + +#### 3.1 Create a new branch + +Please don't use master branch for development. We should create a new branch instead: + +```shell +# checkout master branch +git checkout master +# pull the latest code from official hugegraph +git pull hugegraph +# create new branch: bugfix-branch +git checkout -b bugfix-branch +``` + +#### 3.2 Change the code + +Assume that we need to modify some files like "HugeGraph.java" and "HugeFactory.java": + +```shell +# modify code to fix a bug +vim hugegraph-core/src/main/java/com/baidu/hugegraph/HugeGraph.java +vim hugegraph-core/src/main/java/com/baidu/hugegraph/HugeFactory.java +# run test locally (optional) +mvn test -Pcore-test,memory +``` +Note: In order to be consistent with the code style easily, if you use [IDEA](https://www.jetbrains.com/idea/) as your IDE, you can directly [import](https://www.jetbrains.com/help/idea/configuring-code-style.html) our code style [configuration file](./hugegraph-style.xml). + +#### 3.3 Commit changes to git repo + +After the code has been completed, we submit them to the local git repo: + +```shell +# add files to local git index +git add hugegraph-core/src/main/java/com/baidu/hugegraph/HugeGraph.java +git add hugegraph-core/src/main/java/com/baidu/hugegraph/HugeFactory.java +# commit to local git repo +git commit +``` + +Please edit the commit message after running `git commit`, we can explain what and how to fix a bug or implement a feature, the following is an example: + +```sh +Fix bug: run deploy multiple times + +fix #ISSUE_ID +``` + +> Please remember to fill in the issue id, which was generated by GitHub after issue creation. + +#### 3.4 Push commit to GitHub fork repo + +Push the local commit to GitHub fork repo: + +```shell +# push the local commit to fork repo +git push origin bugfix-branch:bugfix-branch +``` + +Note that since GitHub requires submitting code through `username + token` (instead of using `username + password` directly), you need to create a GitHub token from https://github.com/settings/tokens: +image + +## 4. Create a Pull Request + +Go to the web page of GitHub fork repo, there would be a chance to create a Pull Request after pushing to a new branch, just click button "Compare & pull request" to do it. Then edit the description for proposed changes, which can just be copied from the commit message. + +Please sign the HugeGraph CLA when contributing code for the first time. You can sign the CLA by just posting a Pull Request Comment same as the below format: + +`I have read the CLA Document and I hereby sign the CLA` + +Note: please make sure the email address you used to submit the code is bound to the GitHub account. For how to bind the email address, please refer to https://github.com/settings/emails: +image + +## 5. Code review + + Maintainers will start the code review after all the **automatic** checks are passed: + +- Check: Contributor License Agreement is signed +- Check: Travis CI builds is passed (automatically Test and Deploy) + +The commit will be accepted and merged if there is no problem after review. + +Please click on "Details" to find the problem if any check does not pass. + +If there are checks not passed or changes requested, then continue to modify the code and push again. + +## 6. More changes after review + +If we have not passed the review, don't be discouraged. Usually a commit needs to be reviewed several times before being accepted! Please follow the review comments and make further changes. + +After the further changes, we submit them to the local repo: + +```shell +# commit all updated files in a new commit, +# please feel free to enter any appropriate commit message, note that +# we will squash all commits in the pull request as one commit when +# merging into the master branch. +git commit -a +``` + +> If there are conflicts that prevent the code from being merged, we need to rebase on master branch: +> +> ```shell +> # synchronize the latest code +> git checkout master +> git pull hugegraph +> # rebase on master +> git checkout bugfix-branch +> git rebase -i master +> ``` + +And push it to GitHub fork repo again: + +```shell +# force push the local commit to fork repo +git push -f origin bugfix-branch:bugfix-branch +``` + +GitHub will automatically update the Pull Request after we push it, just wait for code review. diff --git a/content/cn/contribution-guidelines/subscribe.md b/content/cn/contribution-guidelines/subscribe.md new file mode 100644 index 000000000..96a076f74 --- /dev/null +++ b/content/cn/contribution-guidelines/subscribe.md @@ -0,0 +1,29 @@ +--- +title: "订阅社区邮箱" +linkTitle: "订阅社区邮箱" +weight: 2 +--- + +> TODO: translate this article to Chinese + +It is highly recommended to subscribe to the development mailing list to keep up-to-date with the community. + +In the process of using HugeGraph, if you have any questions or ideas, suggestions, you can participate in the HugeGraph community building through the Apache mailing list. Sending a subscription email is also very simple, the steps are as follows: + +1. Email dev-subscribe@hugegraph.apache.org with your own email address, subject and content are arbitrary. + +2. Receive confirmation email and reply. After completing step 1, you will receive a confirmation email from dev-help@hugegraph.apache.org (if not received, please confirm whether the email is automatically classified as spam, promotion email, subscription email, etc.) . Then reply directly to the email, or click on the link in the email to reply quickly, the subject and content are arbitrary. + +3. Receive a welcome email. After completing the above steps, you will receive a welcome email with the subject WELCOME to dev@hugegraph.apache.org, and you have successfully subscribed to the Apache HugeGraph mailing list. + +# Unsubscribe Mailing Lists + +If you do not need to know what's going on with HugeGraph, you can unsubscribe from the mailing list. + +Unsubscribe from the mailing list steps are as follows: + +1. Email dev-unsubscribe@hugegraph.apache.org with your subscribed email address, subject and content are arbitrary. + +2. Receive confirmation email and reply. After completing step 1, you will receive a confirmation email from dev-help@hugegraph.apache.org (if not received, please confirm whether the email is automatically classified as spam, promotion email, subscription email, etc.) . Then reply directly to the email, or click on the link in the email to reply quickly, the subject and content are arbitrary. + +3. Receive a goodbye email. After completing the above steps, you will receive a goodbye email with the subject GOODBYE from dev@hugegraph.apache.org, and you have successfully unsubscribed to the Apache HugeGraph mailing list, and you will not receive emails from dev@hugegraph.apache.org. diff --git a/content/cn/contribution-guidelines/validate-release.md b/content/cn/contribution-guidelines/validate-release.md new file mode 100644 index 000000000..a4068c242 --- /dev/null +++ b/content/cn/contribution-guidelines/validate-release.md @@ -0,0 +1,71 @@ +--- +title: "验证 Apache 发版" +linkTitle: "验证 Apache 发版e" +weight: 3 +--- + +## 验证阶段 + +当内部的临时发布和打包工作完成后, 其他的社区开发者(尤其是 PMC)需要参与到[验证环节](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist)确保某个人发布版本的"正确性 + 完整性", 这里需要**每个人**都尽量参与, 然后后序**邮件回复**的时候说明自己**已检查**了哪些项. (下面是核心项) + +#### 1. 检查 hash 值 + +首先需要检查 `source + binary` 包的文件完整性, 通过 `shasum` 进行校验, 确保和发布到 apache/github 上的 hash 值一致 (一般是 sha512), 这里同0x02的最后一步检验. + +#### 2. 检查 gpg 签名 + +这个就是为了确保发布的包是由**可信赖**的人上传的, 假设 tom 签名后上传, 其他人应该下载 A 的**公钥**然后进行**签名确认**, 相关命令: + +```bash +# 1. 下载项目可信赖公钥到本地 (首次需要) +curl xxx >> PK +gpg --import PK +# 1.2 等待响应后输入 trust 表示信任 tom 的公钥 (其他人名类似) +gpg -edit-key tom + +# 2. 检查签名 (可用 0x03 章节的第 ⑧ 步的 for 循环脚本批量遍历) +gpg --verify xx.asc xxx-source.tar.gz +gpg --verify xx.asc xxx-binary.tar.gz # 注: 我们目前没有 binary 后缀 +``` + +先确认了整体的完整性/一致性, 然后接下来确认具体的内容 (**关键**) + +#### 3. 检查压缩包内容 + +这里分源码包 + 二进制包两个方面, 源码包更为严格, 挑核心的部分说 (完整的列表参考官方 [Wiki](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist), 比较长) + +首先我们需要从 apache 官方的 `release-candidate` 地址下载包到本地 (地址: `dist.apache.org/repos/dist/dev/hugegraph/`) + +##### A. 源码包 + +解压 `xxx-hugegraph-source.tar.gz`后, 进行如下检查: + +1. 文件夹都带有 `incubating`, 且不存在**空的**文件/文件夹 +2. 存在`DISCLAIMER`文件 +3. 存在 `LICENSE` + `NOTICE` 文件并且内容正常 +4. **不存在**任何二进制文件 +5. 源码文件都包含标准 `ASF License` 头 (这个用插件跑一下为主) +6. 检查每个父/子模块的 `pom.xml` 版本号是否一致 (且符合期望) +7. 检查前 3 ~ 5 个 commit 提交, 点进去看看是否修改处和源码文件一致 +8. 最后, 确保源码可以正常/正确编译 (然后看看测试和规范) + +```bash +# 同时也可以检查一下代码风格是否符合规范, 不符合的可以放下一次调整 +mvn clean test -Dcheckstyle.skip=false +``` + +##### B. 二进制包 + +解压 `xxx-hugegraph.tar.gz`后, 进行如下检查: + +1. 文件夹都带有 `incubating` +2. 存在 `LICENSE` + `NOTICE` 文件并且内容正常 +3. 通过 gpg 命令确认每个文件的签名正常 + +**注:** 如果二进制包里面引入了第三方依赖, 则需要更新 LICENSE, 加入第三方依赖的 LICENSE; 若第三方依赖 LICENSE 是 Apache 2.0, 且对应的项目中包含了 NOTICE, 则还需要更新我们的 NOTICE 文件 + +#### 4. 检查官网以及 github 等页面 + +1. 确保官网至少满足 [apache website check](https://whimsy.apache.org/pods/project/hugegraph), 以及没有死链等 +2. 更新**下载链接**以及版本更新说明 +3. ….. diff --git a/content/cn/docs/changelog/hugegraph-1.0.0-release-notes.md b/content/cn/docs/changelog/hugegraph-1.0.0-release-notes.md new file mode 100644 index 000000000..4f6d455e8 --- /dev/null +++ b/content/cn/docs/changelog/hugegraph-1.0.0-release-notes.md @@ -0,0 +1,56 @@ +--- +title: "HugeGraph 1.0.0 Release Notes" +linkTitle: "Release-1.0.0" +weight: 1 +--- + +> TODO: translate this article to Chinese + +### Server (API & Client) + +#### 接口更新 + +- xx +- xx + +#### 其它修改 + +- xx +- xx + +### Core & Server + +#### 功能更新 + +- xx +- xx + +#### BUG修复 + +- xx +- xx + +#### 配置项修改： + +- xx +- xx + +#### 其它修改 + +- xx +- xx + +### Toolchain + +- xx +- xx + +### Computer + +- xx +- xx + +### Commons + +- xx +- xx diff --git a/content/en/docs/changelog/hugegraph-1.0.0-release-notes.md b/content/en/docs/changelog/hugegraph-1.0.0-release-notes.md new file mode 100644 index 000000000..523da7779 --- /dev/null +++ b/content/en/docs/changelog/hugegraph-1.0.0-release-notes.md @@ -0,0 +1,54 @@ +--- +title: "HugeGraph 1.0.0 Release Notes" +linkTitle: "Release-1.0.0" +weight: 1 +--- + +### Server (API & Client) + +#### 接口更新 + +- xx +- xx + +#### 其它修改 + +- xx +- xx + +### Core & Server + +#### 功能更新 + +- xx +- xx + +#### BUG修复 + +- xx +- xx + +#### 配置项修改： + +- xx +- xx + +#### 其它修改 + +- xx +- xx + +### Toolchain + +- xx +- xx + +### Computer + +- xx +- xx + +### Commons + +- xx +- xx diff --git a/content/en/docs/contribution-guidelines/_index.md b/content/en/docs/contribution-guidelines/_index.md index ea28e2d58..2cdf8103d 100755 --- a/content/en/docs/contribution-guidelines/_index.md +++ b/content/en/docs/contribution-guidelines/_index.md @@ -2,4 +2,4 @@ title: "Contribution Guidelines" linkTitle: "Contribution Guidelines" weight: 9 ---- \ No newline at end of file +--- diff --git a/content/en/docs/contribution-guidelines/validate-release.md b/content/en/docs/contribution-guidelines/validate-release.md new file mode 100644 index 000000000..99a96404c --- /dev/null +++ b/content/en/docs/contribution-guidelines/validate-release.md @@ -0,0 +1,73 @@ +--- +title: "Validate Apache Release" +linkTitle: "Validate Apache Release" +weight: 3 +--- + +> TODO: Translate this article to English! + +## 验证阶段 + +当内部的临时发布和打包工作完成后, 其他的社区开发者(尤其是 PMC)需要参与到[验证环节](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist)确保某个人发布版本的"正确性 + 完整性", 这里需要**每个人**都尽量参与, 然后后序**邮件回复**的时候说明自己**已检查**了哪些项. (下面是核心项) + +#### 1. 检查 hash 值 + +首先需要检查 `source + binary` 包的文件完整性, 通过 `shasum` 进行校验, 确保和发布到 apache/github 上的 hash 值一致 (一般是 sha512), 这里同0x02的最后一步检验. + +#### 2. 检查 gpg 签名 + +这个就是为了确保发布的包是由**可信赖**的人上传的, 假设 tom 签名后上传, 其他人应该下载 A 的**公钥**然后进行**签名确认**, 相关命令: + +```bash +# 1. 下载项目可信赖公钥到本地 (首次需要) +curl xxx >> PK +gpg --import PK +# 1.2 等待响应后输入 trust 表示信任 tom 的公钥 (其他人名类似) +gpg -edit-key tom + +# 2. 检查签名 (可用 0x03 章节的第 ⑧ 步的 for 循环脚本批量遍历) +gpg --verify xx.asc xxx-source.tar.gz +gpg --verify xx.asc xxx-binary.tar.gz # 注: 我们目前没有 binary 后缀 +``` + +先确认了整体的完整性/一致性, 然后接下来确认具体的内容 (**关键**) + +#### 3. 检查压缩包内容 + +这里分源码包 + 二进制包两个方面, 源码包更为严格, 挑核心的部分说 (完整的列表参考官方 [Wiki](https://cwiki.apache.org/confluence/display/INCUBATOR/Incubator+Release+Checklist), 比较长) + +首先我们需要从 apache 官方的 `release-candidate` 地址下载包到本地 (地址: `dist.apache.org/repos/dist/dev/hugegraph/`) + +##### A. 源码包 + +解压 `xxx-hugegraph-source.tar.gz`后, 进行如下检查: + +1. 文件夹都带有 `incubating`, 且不存在**空的**文件/文件夹 +2. 存在`DISCLAIMER`文件 +3. 存在 `LICENSE` + `NOTICE` 文件并且内容正常 +4. **不存在**任何二进制文件 +5. 源码文件都包含标准 `ASF License` 头 (这个用插件跑一下为主) +6. 检查每个父/子模块的 `pom.xml` 版本号是否一致 (且符合期望) +7. 检查前 3 ~ 5 个 commit 提交, 点进去看看是否修改处和源码文件一致 +8. 最后, 确保源码可以正常/正确编译 (然后看看测试和规范) + +```bash +# 同时也可以检查一下代码风格是否符合规范, 不符合的可以放下一次调整 +mvn clean test -Dcheckstyle.skip=false +``` + +##### B. 二进制包 + +解压 `xxx-hugegraph.tar.gz`后, 进行如下检查: + +1. 文件夹都带有 `incubating` +2. 存在 `LICENSE` + `NOTICE` 文件并且内容正常 +3. 通过 gpg 命令确认每个文件的签名正常 + +**注:** 如果二进制包里面引入了第三方依赖, 则需要更新 LICENSE, 加入第三方依赖的 LICENSE; 若第三方依赖 LICENSE 是 Apache 2.0, 且对应的项目中包含了 NOTICE, 则还需要更新我们的 NOTICE 文件 + +#### 4. 检查官网以及 github 等页面 + +1. 确保官网至少满足 [apache website check](https://whimsy.apache.org/pods/project/hugegraph), 以及没有死链等 +2. 更新**下载链接**以及版本更新说明 +3. ...