This is an automated email from the ASF dual-hosted git repository.
jin pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-hugegraph-doc.git
The following commit(s) were added to refs/heads/master by this push:
new 3ec04b09 release: add apache 1.0.0 doc & how to validate (#162)
3ec04b09 is described below
commit 3ec04b09228d5203d883ef49f2d5893bddf2ddb4
Author: imbajin <[email protected]>
AuthorDate: Fri Dec 30 19:36:31 2022 +0800
release: add apache 1.0.0 doc & how to validate (#162)
---
.../docs => cn}/contribution-guidelines/_index.md | 2 +-
content/cn/contribution-guidelines/contribute.md | 169 +++++++++++++++++++++
content/cn/contribution-guidelines/subscribe.md | 29 ++++
.../cn/contribution-guidelines/validate-release.md | 71 +++++++++
.../changelog/hugegraph-1.0.0-release-notes.md | 56 +++++++
.../changelog/hugegraph-1.0.0-release-notes.md | 54 +++++++
content/en/docs/contribution-guidelines/_index.md | 2 +-
.../contribution-guidelines/validate-release.md | 73 +++++++++
8 files changed, 454 insertions(+), 2 deletions(-)
diff --git a/content/en/docs/contribution-guidelines/_index.md
b/content/cn/contribution-guidelines/_index.md
similarity index 95%
copy from content/en/docs/contribution-guidelines/_index.md
copy to content/cn/contribution-guidelines/_index.md
index ea28e2d5..2cdf8103 100755
--- a/content/en/docs/contribution-guidelines/_index.md
+++ b/content/cn/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/cn/contribution-guidelines/contribute.md
b/content/cn/contribution-guidelines/contribute.md
new file mode 100644
index 00000000..50a90adf
--- /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:
+
+<img width="884" alt="image"
src="https://user-images.githubusercontent.com/9625821/159643158-8bf72c0a-93c3-4a58-8912-7b2ab20ced1d.png";>
+
+## 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 "[email protected]"
+ ```
+
+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:
+<img width="1280" alt="image"
src="https://user-images.githubusercontent.com/9625821/163524204-7fe0e6bf-9c8b-4b1a-ac65-6a0ac423eb16.png";>
+
+## 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:
+<img width="1280" alt="image"
src="https://user-images.githubusercontent.com/9625821/163522445-2a50a72a-dea2-434f-9868-3a0d40d0d037.png";>
+
+## 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 00000000..96a076f7
--- /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 [email protected] 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 [email protected] (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 [email protected], 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 [email protected] 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 [email protected] (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 [email protected], and
you have successfully unsubscribed to the Apache HugeGraph mailing list, and
you will not receive emails from [email protected].
diff --git a/content/cn/contribution-guidelines/validate-release.md
b/content/cn/contribution-guidelines/validate-release.md
new file mode 100644
index 00000000..a4068c24
--- /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 00000000..4f6d455e
--- /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 00000000..523da777
--- /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 ea28e2d5..2cdf8103 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 00000000..99a96404
--- /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. ...
![https://user-images.githubusercontent.com/9625821/159643158-8bf72c0a-93c3-4a58-8912-7b2ab20ced1d.png"](https://user-images.githubusercontent.com/9625821/159643158-8bf72c0a-93c3-4a58-8912-7b2ab20ced1d.png"){kind=link}
![https://user-images.githubusercontent.com/9625821/163524204-7fe0e6bf-9c8b-4b1a-ac65-6a0ac423eb16.png"](https://user-images.githubusercontent.com/9625821/163524204-7fe0e6bf-9c8b-4b1a-ac65-6a0ac423eb16.png"){kind=link}
![https://user-images.githubusercontent.com/9625821/163522445-2a50a72a-dea2-434f-9868-3a0d40d0d037.png"](https://user-images.githubusercontent.com/9625821/163522445-2a50a72a-dea2-434f-9868-3a0d40d0d037.png"){kind=link}