如何参与 HugeGraph 社区

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

建议: 使用 GitHub desktop 可以大幅简化和改善你提交 PR/Commit 的过程, 特别适合新人

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

  2. Fork HugeGraph repo from GitHub: https://github.com/apache/incubator-hugegraph/fork

  3. Clone code from fork repo to local: https://github.com/${GITHUB_USER_NAME}/hugegraph

    1. # clone code from remote to local repo
    2. git clone https://github.com/${GITHUB_USER_NAME}/hugegraph

  4. Configure local HugeGraph repo

    1. cd hugegraph
    3. # add upstream to synchronize the latest code
    4. git remote add hugegraph https://github.com/apache/hugegraph
    6. # set name and email to push code to github
    7. git config user.name "{full-name}" # like "Jermy Li"
    8. git config user.email "{email-address-of-github}" # like "jermy@apache.org"

2. Create an Issue on GitHub

If you encounter bugs or have any questions, please go to GitHub Issues to report them and feel free to create an issue.

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:

  1. # checkout master branch
  2. git checkout master
  3. # pull the latest code from official hugegraph
  4. git pull hugegraph
  5. # create new branch: bugfix-branch
  6. git checkout -b bugfix-branch

3.2 Change the code

Assume that we need to modify some files like “HugeGraph.java” and “HugeFactory.java”:

  1. # modify code to fix a bug
  2. vim hugegraph-core/src/main/java/org/apache/hugegraph/HugeGraph.java
  3. vim hugegraph-core/src/main/java/org/apache/hugegraph/HugeFactory.java
  4. # run test locally (optional)
  5. mvn test -Pcore-test,memory

Note: In order to be consistent with the code style easily, if you use IDEA as your IDE, you can directly import our code style configuration file.

3.2.1 添加第三方依赖

如果我们要在 HugeGraph 项目中添加新的第三方依赖, 我们需要做下面的几件事情：

  1. 找到第三方依赖的仓库，将依赖的 license 文件放到 ./hugegraph-dist/release-docs/licenses/ 路径下。
  2. 在./hugegraph-dist/release-docs/LICENSE 中声明该依赖的 LICENSE 信息。
  3. 找到仓库里的 NOTICE 文件，将其追加到 ./hugegraph-dist/release-docs/NOTICE 文件后面（如果没有NOTICE文件则跳过这一步）。
  4. 本地执行./hugegraph-dist/scripts/dependency/regenerate_known_dependencies.sh 脚本来更新依赖列表known-dependencies.txt (或者手动更新)。

例如：在项目中引入了第三方新依赖 -> ant-1.9.1.jar

ant-1.9.1.jar 的 license 信息需要在 LICENSE 文件中指定，notice 信息需要在 NOTICE 文件中指定。 ant-1.9.1.jar 对应的详细 LICENSE 文件需要复制到我们的 licenses/ 目录下。最后更新 known-dependencies.txt 文件。

3.3 Commit changes to git repo

After the code has been completed, we submit them to the local git repo:

  1. # add files to local git index
  2. git add hugegraph-core/src/main/java/org/apache/hugegraph/HugeGraph.java
  3. git add hugegraph-core/src/main/java/org/apache/hugegraph/HugeFactory.java
  4. # commit to local git repo
  5. 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:

  1. Fix bug: run deploy multiple times 
  3. 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:

  1. # push the local commit to fork repo
  2. 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.

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:

  1. # commit all updated files in a new commit,
  2. # please feel free to enter any appropriate commit message, note that
  3. # we will squash all commits in the pull request as one commit when
  4. # merging into the master branch.
  5. git commit -a

If there are conflicts that prevent the code from being merged, we need to rebase on master branch:

  1. # synchronize the latest code
  2. git checkout master
  3. git pull hugegraph
  4. # rebase on master
  5. git checkout bugfix-branch
  6. git rebase -i master

And push it to GitHub fork repo again:

  1. # force push the local commit to fork repo
  2. git push -f origin bugfix-branch:bugfix-branch

GitHub will automatically update the Pull Request after we push it, just wait for code review.

Last modified December 21, 2023: chore(website): fix link path (#309) (4f07fcd5)