From 063e6eb623a7a7565f8329939f2fceb2fb3af47d Mon Sep 17 00:00:00 2001 From: acezen Date: Tue, 21 Mar 2023 11:56:33 +0800 Subject: [PATCH 1/7] Add coding style guide doc --- docs/development/code_style_guide.md | 40 +++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/docs/development/code_style_guide.md b/docs/development/code_style_guide.md index 6dba184e2be5..be4914aa0164 100644 --- a/docs/development/code_style_guide.md +++ b/docs/development/code_style_guide.md @@ -1,17 +1,51 @@ # Code Style Guide -TBF -(this document describes the code style we choosed to follow for GraphScope.) +This document describes the coding style guidelines for GraphScope's codebase. +Following consistent coding standards across the codebase ensures readability, maintainability, and code quality. ## C++ Style +We follow the [Google C++ Style Guide][1] for coding standards in C++. + ## Python Style +We follow the [black][2] code style for Python coding standards. + ## Rust Style +We follow a [custom style][3] for coding standards in Rust. + ## Java Style +we follow the [Google Java Style Guide][4] for coding standards in Java. + ## Script Style -## Style Linter and Checker \ No newline at end of file +We follow the [Google Shell Style Guide][5] for coding standards in shell script. + +## Style Linter and Checker + +GraphScope uses linters and checkers for each language to enforce code style rules. + +- C++: [clang-format-8][6] and [cpplint][7] +- Python: [Flake8][8] +- Rust: [rust-fmt][9] +- Java: [google-java-format][10] + +## Conclusion + +In conclusion, following a consistent code style guide is crucial for maintaining code quality and readability. By adhering to these guidelines, we can ensure that code in GraphScope follows best practices and is easy to read, understand, and maintain. It is important to note that these guidelines are not set in stone and may evolve over time as the project grows and changes. Therefore, we encourage all contributors to review and suggest improvements to this document as needed. + + +[1]: https://google.github.io/styleguide/cppguide.html +[2]: https://github.com/psf/black +[3]: https://github.com/alibaba/GraphScope/blob/main/interactive_engine/executor/rustfmt.toml +[4]: https://google.github.io/styleguide/javaguide.html +[5]: https://google.github.io/styleguide/shellguide.html +[6]: https://releases.llvm.org/8.0.0/tools/clang/docs/ClangFormat.html +[7]: https://github.com/cpplint/cpplint +[8]: https://flake8.pycqa.org/en/latest/ +[9]: https://github.com/rust-lang/rustfmt +[10]: https://github.com/google/google-java-format + From c961a4ef4bd4e3f2e5c31c432eb913519c6850ea Mon Sep 17 00:00:00 2001 From: acezen Date: Tue, 21 Mar 2023 16:02:45 +0800 Subject: [PATCH 2/7] Add how to contribute guide doc --- docs/development/how_to_contribute.md | 182 +++++++++++++++++++++++++- 1 file changed, 181 insertions(+), 1 deletion(-) diff --git a/docs/development/how_to_contribute.md b/docs/development/how_to_contribute.md index 0422a57e3190..67320df3ebea 100644 --- a/docs/development/how_to_contribute.md +++ b/docs/development/how_to_contribute.md @@ -1,4 +1,184 @@ # How to Contribute +**Thanks for your interest in the GraphScope project.** + +GraphScope is a large project and may seem overwhelming when you’re first getting involved. Contributing code is great, +but that’s probably not the first place to start. There are lots of ways to make valuable contributions to the project and community, +from improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into GraphAr itself. + +## Code of Conduct + +Please read our [Code of Conduct][1] before contributing or engaging in our community. + +## Community + +A good first step to getting involved in the GraphScope project is to join us and participate in discussions where you can. there are several ways to connect with us. + +### GitHub Discussion + +We use [GitHub Discussion](https://github.com/alibaba/GraphScope/discussions) as a way to ask questions. Feel free to ask qustion if you have questions about +GraphScope or issues with your own code. + +### Slack + TBF -(This document is intended to help you get started contributing to GraphScope project.) \ No newline at end of file + +### DingTalk + +TBF + +## Bug Report + +If you find a bug in GraphAr, first make sure that you are testing against the [latest version of GraphScope](https://github.com/alibaba/GraphAr/tree/main), +your issue may already have been fixed. If not, search our [issues list](https://github.com/alibaba/GraphScope/issues) +on GitHub in case a similar issue has already been opened. + +If you get confirmation of your bug, [file a bug issue](https://github.com/alibaba/GraphScope/issues/new?assignees=&labels=&template=bug_report.md&title=%5BBUG%5D+) before starting to code. When submitting an issue, please include a clear and concise description of the problem, any relevant code or error messages, and steps to reproduce the issue. + +## Request Feature + +If you find yourself wishing for a feature that doesn't exist in GraphScope, you are probably not alone. +There are bound to be others out there with similar needs. Many of the features that GraphScope has today +have been added because our users saw the need. + +[Open a feature request issue](https://github.com/alibaba/GraphScope/issues/new?assignees=&labels=&template=feature_request.md&title=) on GitHub which describes the feature you would +like to see, why you need it, and how it should work. + +## Improve Documentation + +A great way to contribute to the project is to improve documentation. If you found some docs to be incomplete or inaccurate, share your hard-earned knowledge with the rest of the community. + +Documentation improvements are also a great way to gain some experience with our submission and review process, discussed below, without requiring a lot of local development environment setup. In fact, many documentation-only changes can be made directly in the GitHub web interface by clicking the “edit” button. This will handle making a fork and a pull request for you. + +TBF: add a link to how to helping with documentation +TBF: add a link to how to build the documentation + + +## Contributing code and documentation changes + +If you would like to contribute a new feature or a bug fix to GraphScope, +please discuss your idea first on the GitHub issue. If there is no GitHub issue +for your idea, please open one. It may be that somebody is already working on +it, or that there are particular complexities that you should know about before +starting the implementation. There are often a number of ways to fix a problem +and it is important to find the right approach before spending time on a PR +that cannot be merged. + +### Install pre-commit + +GraphScope use `pre-commit`_ to ensure no secrets are accidentally committed +into the Git repository, you could first install `pre-commit`_ by + +```bash + $ pip3 install pre-commit +``` + +The configure the necessary pre-commit hooks with + +```bash + $ pre-commit install --install-hooks +``` + +### Minor Fixes + +Any functionality change should have a GitHub issue opened. For minor changes that +affect documentation, you do not need to open up a GitHub issue. Instead you can +prefix the title of your PR with "[MINOR] " if meets the following guidelines: + +* Grammar, usage and spelling fixes that affect no more than 2 files +* Documentation updates affecting no more than 2 files and not more + than 500 words. + +### Fork & create a branch + +You will need to fork the main GraphScope code and clone it to your local machine. See +[github help page](https://help.github.com/articles/fork-a-repo) for help. + +Then you need to create a branch with a descriptive name. + +A good branch name would be (where issue #42 is the ticket you're working on): + +```bash + $ git checkout -b 42-add-chinese-translations +``` + +### Get the test suite running + +See [how to test](./how_to_test.md) for detail. + +### Implement your fix or feature + +At this point, you're ready to make your changes! Feel free to ask for help; +everyone is a beginner at first :smile_cat: + +### Get the code format & style right + +Your patch should follow the same conventions & pass the same code quality +checks as the rest of the project. Please follw [the code style guide](code_style_guide.md) to get the code format and style right. + +### Submitting your changes + +See [How to submit pull request](how_to_submit_pr) + +### Discussing and keeping your Pull Request updated + +You will probably get feedback or requests for changes to your pull request. +This is a big part of the submission process so don't be discouraged! +It is a necessary part of the process in order to evaluate whether the changes +are correct and necessary. + +If a maintainer asks you to "rebase" your PR, they're saying that a lot of code +has changed, and that you need to update your branch so it's easier to merge. + +To learn more about rebasing in Git, there are a lot of [good](http://git-scm.com/book/en/Git-Branching-Rebasing) + [resources](https://help.github.com/en/github/using-git/about-git-rebase), but here's the suggested workflow: + +```bash + $ git checkout 42-add-chinese-translations + $ git pull --rebase upstream main + $ git push --force-with-lease 42-add-chinese-translations +``` + +Feel free to post a comment in the pull request to ping reviewers if you are awaiting an answer +on something. If you encounter words or acronyms that seem unfamiliar, refer to this [glossary](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/glossary.md). + +### Merging a PR (maintainers only) + +A PR can only be merged into main by a maintainer if: + +* It is passing CI. +* It has been approved by at least two maintainers. If it was a maintainer who + opened the PR, only one extra approval is needed. +* It has no requested changes. +* It is up to date with current main. + +### Shipping a release (maintainers only) + +TODO(dongze): TBF + + +## How to Review Pull Requests + +We welcome contributions from the community and encourage everyone to review pull requests. When reviewing a pull request, please consider the following: + +- Does the code follow our [Code of Conduct][1]? +- Does the code solve the problem described in the issue or feature request? +- Are there any potential side effects or edge cases that need to be considered? +- Are there any tests included to ensure the code works as expected? + +If you have any questions or concerns about a pull request, please comment on the pull request or reach out to the contributor directly. + +## Continuous integration testing + +All pull requests that contain changes to code must be run through +continuous integration (CI) testing at [Github Actions](https://github.com/alibaba/GarphScope/actions) + +The pull request change will trigger a CI testing run. Ideally, the code change +will pass ("be green") on all platform configurations supported by GraphAr. +This means that all tests pass and there are no linting errors. In reality, +however, it is not uncommon for the CI infrastructure itself to fail on specific +platforms ("be red"). It is vital to visually inspect the results of all failed ("red") tests +to determine whether the failure was caused by the changes in the pull request. + +[1]: https://github.com/alibaba/GraphScope/blob/main/CODE_OF_CONDUCT.md + From 480e906ca8477b0ed436aca8a81dbd0b612bba77 Mon Sep 17 00:00:00 2001 From: acezen Date: Tue, 21 Mar 2023 16:09:41 +0800 Subject: [PATCH 3/7] tiny fix --- docs/development/how_to_contribute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/how_to_contribute.md b/docs/development/how_to_contribute.md index 67320df3ebea..979164974c21 100644 --- a/docs/development/how_to_contribute.md +++ b/docs/development/how_to_contribute.md @@ -29,7 +29,7 @@ TBF ## Bug Report -If you find a bug in GraphAr, first make sure that you are testing against the [latest version of GraphScope](https://github.com/alibaba/GraphAr/tree/main), +If you find a bug in GraphAr, first make sure that you are testing against the [latest version of GraphScope](https://github.com/alibaba/GraphScope/tree/main), your issue may already have been fixed. If not, search our [issues list](https://github.com/alibaba/GraphScope/issues) on GitHub in case a similar issue has already been opened. From b9698d322124ba6338e48e33e31603a2949d614f Mon Sep 17 00:00:00 2001 From: acezen Date: Tue, 21 Mar 2023 16:40:27 +0800 Subject: [PATCH 4/7] Add instructions about how to use linter and checker --- docs/development/code_style_guide.md | 38 ++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/development/code_style_guide.md b/docs/development/code_style_guide.md index be4914aa0164..6d17767b76aa 100644 --- a/docs/development/code_style_guide.md +++ b/docs/development/code_style_guide.md @@ -33,6 +33,44 @@ GraphScope uses linters and checkers for each language to enforce code style rul - Rust: [rust-fmt][9] - Java: [google-java-format][10] +Each linter can be included in the build process to ensure that code adheres to the style guide. + +For C++, format and lint the code by the MakeFile command: + +```bash + $ make graphscope_clformat + $ make graphscope_cpplint +``` + +For Rust, we provide a shell script to do the format check: + +```bash + $ cd interactive_engine/executor + $ ./check_format.sh +``` + +For Python: + +```bash + $ pip3 install -r coordinator/requirements-dev.txt + $ pushd python + $ python3 -m isort --check --diff . + $ python3 -m black --check --diff . + $ python3 -m flake8 . + $ popd + $ python3 -m isort --check --diff . + $ python3 -m black --check --diff . + $ python3 -m flake8 . +``` + +For Java: + +```bash + $ wget https://github.com/google/google-java-format/releases/download/v1.13.0/google-java-format-1.13.0-all-deps.jar + $ files_to_format=$(git ls-files *.java) + $ java -jar google-java-format-1.13.0-all-deps.jar --aosp --skip-javadoc-formatting -i $files_to_format +``` + ## Conclusion In conclusion, following a consistent code style guide is crucial for maintaining code quality and readability. By adhering to these guidelines, we can ensure that code in GraphScope follows best practices and is easy to read, understand, and maintain. It is important to note that these guidelines are not set in stone and may evolve over time as the project grows and changes. Therefore, we encourage all contributors to review and suggest improvements to this document as needed. From 1a9d306eda14642f180d155a6bf7d01d35eed445 Mon Sep 17 00:00:00 2001 From: acezen Date: Tue, 21 Mar 2023 16:54:04 +0800 Subject: [PATCH 5/7] tiny fix --- docs/development/code_style_guide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/development/code_style_guide.md b/docs/development/code_style_guide.md index 6d17767b76aa..7649117dbcef 100644 --- a/docs/development/code_style_guide.md +++ b/docs/development/code_style_guide.md @@ -58,6 +58,7 @@ For Python: $ python3 -m black --check --diff . $ python3 -m flake8 . $ popd + $ pushd coordinator $ python3 -m isort --check --diff . $ python3 -m black --check --diff . $ python3 -m flake8 . From a6a38d9c19b99e103ed56c2ab2dd006296c7d317 Mon Sep 17 00:00:00 2001 From: acezen Date: Fri, 24 Mar 2023 10:29:15 +0800 Subject: [PATCH 6/7] Proofread and improve docstring of development/code_style_guide.md --- docs/development/code_style_guide.md | 88 ++++++++++++++-------------- 1 file changed, 44 insertions(+), 44 deletions(-) diff --git a/docs/development/code_style_guide.md b/docs/development/code_style_guide.md index 7649117dbcef..574a51e08313 100644 --- a/docs/development/code_style_guide.md +++ b/docs/development/code_style_guide.md @@ -1,90 +1,90 @@ # Code Style Guide - -This document describes the coding style guidelines for GraphScope's codebase. -Following consistent coding standards across the codebase ensures readability, maintainability, and code quality. +This document provides the coding style guidelines for GraphScope's codebase, which includes C++, Python, Rust, Java, and shell scripts. +Adhering to consistent coding standards across the codebase promotes maintainability, readability, and code quality. ## C++ Style -We follow the [Google C++ Style Guide][1] for coding standards in C++. +We follow the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) for coding standards in C++. ## Python Style -We follow the [black][2] code style for Python coding standards. +We follow the [black](https://github.com/psf/black) code style for Python coding standards. ## Rust Style -We follow a [custom style][3] for coding standards in Rust. +We follow the [rust-lang code style](https://github.com/rust-lang/style-team/blob/master/guide/guide.md), +with the GraphScope custom [configuration](https://github.com/alibaba/GraphScope/blob/main/interactive_engine/executor/rustfmt.toml) for coding standards in Rust. ## Java Style -we follow the [Google Java Style Guide][4] for coding standards in Java. +we follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html) for coding standards in Java. ## Script Style -We follow the [Google Shell Style Guide][5] for coding standards in shell script. +We follow the [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html) for coding standards in shell script. ## Style Linter and Checker -GraphScope uses linters and checkers for each language to enforce code style rules. +GraphScope uses different linters and checkers for each language to enforce code style rules: -- C++: [clang-format-8][6] and [cpplint][7] -- Python: [Flake8][8] -- Rust: [rust-fmt][9] -- Java: [google-java-format][10] +- C++: [clang-format-8](https://releases.llvm.org/8.0.0/tools/clang/docs/ClangFormat.html) and [cpplint](https://github.com/cpplint/cpplint) +- Python: [Flake8](https://flake8.pycqa.org/en/latest/) +- Rust: [rust-fmt](https://github.com/rust-lang/rustfmt) +- Java: [google-java-format](https://github.com/google/google-java-format) -Each linter can be included in the build process to ensure that code adheres to the style guide. +Each linter can be included in the build process to ensure that the code adheres to the style guide. +Below are the commands to check the code style in each language: For C++, format and lint the code by the MakeFile command: ```bash + # format $ make graphscope_clformat + # lint $ make graphscope_cpplint ``` -For Rust, we provide a shell script to do the format check: +For Python: + +- Install dependencies first: ```bash - $ cd interactive_engine/executor - $ ./check_format.sh + $ pip3 install -r coordinator/requirements-dev.txt ``` -For Python: +- Check the style: ```bash - $ pip3 install -r coordinator/requirements-dev.txt - $ pushd python - $ python3 -m isort --check --diff . - $ python3 -m black --check --diff . - $ python3 -m flake8 . - $ popd - $ pushd coordinator - $ python3 -m isort --check --diff . - $ python3 -m black --check --diff . - $ python3 -m flake8 . + pushd python + python3 -m isort --check --diff . + python3 -m black --check --diff . + python3 -m flake8 . + popd + pushd coordinator + python3 -m isort --check --diff . + python3 -m black --check --diff . + python3 -m flake8 . ``` -For Java: +For Rust, we provide a shell script to do the format check: ```bash - $ wget https://github.com/google/google-java-format/releases/download/v1.13.0/google-java-format-1.13.0-all-deps.jar - $ files_to_format=$(git ls-files *.java) - $ java -jar google-java-format-1.13.0-all-deps.jar --aosp --skip-javadoc-formatting -i $files_to_format + $ cd interactive_engine/executor + $ ./check_format.sh ``` -## Conclusion +For Java: -In conclusion, following a consistent code style guide is crucial for maintaining code quality and readability. By adhering to these guidelines, we can ensure that code in GraphScope follows best practices and is easy to read, understand, and maintain. It is important to note that these guidelines are not set in stone and may evolve over time as the project grows and changes. Therefore, we encourage all contributors to review and suggest improvements to this document as needed. +- Download the google-java-format tool: +```bash + $ wget https://github.com/google/google-java-format/releases/download/v1.13.0/google-java-format-1.13.0-all-deps.jar +``` -[1]: https://google.github.io/styleguide/cppguide.html -[2]: https://github.com/psf/black -[3]: https://github.com/alibaba/GraphScope/blob/main/interactive_engine/executor/rustfmt.toml -[4]: https://google.github.io/styleguide/javaguide.html -[5]: https://google.github.io/styleguide/shellguide.html -[6]: https://releases.llvm.org/8.0.0/tools/clang/docs/ClangFormat.html -[7]: https://github.com/cpplint/cpplint -[8]: https://flake8.pycqa.org/en/latest/ -[9]: https://github.com/rust-lang/rustfmt -[10]: https://github.com/google/google-java-format +- Check the style: +```bash + $ files_to_format=$(git ls-files *.java) + $ java -jar google-java-format-1.13.0-all-deps.jar --aosp --skip-javadoc-formatting -i $files_to_format +``` From 68757f2824de4f0524f7fe614037e7b330f04f1b Mon Sep 17 00:00:00 2001 From: acezen Date: Fri, 24 Mar 2023 14:26:14 +0800 Subject: [PATCH 7/7] Proofread and improve by cursor --- docs/development/code_style_guide.md | 40 +++---- docs/development/how_to_contribute.md | 145 ++++++++++++-------------- 2 files changed, 84 insertions(+), 101 deletions(-) diff --git a/docs/development/code_style_guide.md b/docs/development/code_style_guide.md index 574a51e08313..03486abd4873 100644 --- a/docs/development/code_style_guide.md +++ b/docs/development/code_style_guide.md @@ -9,7 +9,7 @@ We follow the [Google C++ Style Guide](https://google.github.io/styleguide/cppgu ## Python Style -We follow the [black](https://github.com/psf/black) code style for Python coding standards. +We follow the [black](https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html) code style for Python coding standards. ## Rust Style @@ -39,10 +39,10 @@ Below are the commands to check the code style in each language: For C++, format and lint the code by the MakeFile command: ```bash - # format - $ make graphscope_clformat - # lint - $ make graphscope_cpplint +# format +$ make graphscope_clformat +# lint +$ make graphscope_cpplint ``` For Python: @@ -50,28 +50,28 @@ For Python: - Install dependencies first: ```bash - $ pip3 install -r coordinator/requirements-dev.txt +$ pip3 install -r coordinator/requirements-dev.txt ``` - Check the style: ```bash - pushd python - python3 -m isort --check --diff . - python3 -m black --check --diff . - python3 -m flake8 . - popd - pushd coordinator - python3 -m isort --check --diff . - python3 -m black --check --diff . - python3 -m flake8 . +$ pushd python +$ python3 -m isort --check --diff . +$ python3 -m black --check --diff . +$ python3 -m flake8 . +$ popd +$ pushd coordinator +$ python3 -m isort --check --diff . +$ python3 -m black --check --diff . +$ python3 -m flake8 . ``` For Rust, we provide a shell script to do the format check: ```bash - $ cd interactive_engine/executor - $ ./check_format.sh +$ cd interactive_engine/executor +$ ./check_format.sh ``` For Java: @@ -79,12 +79,12 @@ For Java: - Download the google-java-format tool: ```bash - $ wget https://github.com/google/google-java-format/releases/download/v1.13.0/google-java-format-1.13.0-all-deps.jar +$ wget https://github.com/google/google-java-format/releases/download/v1.13.0/google-java-format-1.13.0-all-deps.jar ``` - Check the style: ```bash - $ files_to_format=$(git ls-files *.java) - $ java -jar google-java-format-1.13.0-all-deps.jar --aosp --skip-javadoc-formatting -i $files_to_format +$ files_to_format=$(git ls-files *.java) +$ java -jar google-java-format-1.13.0-all-deps.jar --aosp --skip-javadoc-formatting -i $files_to_format ``` diff --git a/docs/development/how_to_contribute.md b/docs/development/how_to_contribute.md index 979164974c21..1a480cacd591 100644 --- a/docs/development/how_to_contribute.md +++ b/docs/development/how_to_contribute.md @@ -2,157 +2,143 @@ **Thanks for your interest in the GraphScope project.** -GraphScope is a large project and may seem overwhelming when you’re first getting involved. Contributing code is great, -but that’s probably not the first place to start. There are lots of ways to make valuable contributions to the project and community, -from improving the documentation, submitting bug reports and feature requests or writing code which can be incorporated into GraphAr itself. +GraphScope is an open-source project focused on large-scale graph computation with a friendly community of developers eager to help new contributors. +We welcome contributions of all types, from code improvements to documentation. ## Code of Conduct -Please read our [Code of Conduct][1] before contributing or engaging in our community. +Before contributing to or engaging with our community, please read our [Code of Conduct](https://github.com/alibaba/GraphScope/blob/main/CODE_OF_CONDUCT.md). ## Community -A good first step to getting involved in the GraphScope project is to join us and participate in discussions where you can. there are several ways to connect with us. +A good first step to getting involved in the GraphScope project is to participate in our discussions and join us in our different communication channels. +Here are several ways to connect with us: ### GitHub Discussion -We use [GitHub Discussion](https://github.com/alibaba/GraphScope/discussions) as a way to ask questions. Feel free to ask qustion if you have questions about -GraphScope or issues with your own code. +We use [GitHub Discussion](https://github.com/alibaba/GraphScope/discussions) to ask and answer questions. Feel free to ask any questions you may have about GraphScope or issues you've encountered with your own code. ### Slack -TBF +Join in the [Slack channel](http://slack.graphscope.io) for discussion. -### DingTalk +## Reporting Bugs -TBF +If you find a bug in GraphScope, first test against the [latest version of GraphScope](https://github.com/alibaba/GraphScope/tree/main) +to ensure your issue hasn't already been fixed. If not, search our [issues list](https://github.com/alibaba/GraphScope/issues) +on GitHub to see if a similar issue has already been opened. -## Bug Report +If you confirm that the bug hasn't already been reported [file a bug issue](https://github.com/alibaba/GraphScope/issues/new?assignees=&labels=&template=bug_report.md&title=%5BBUG%5D+) +before writing any code. When submitting an issue, please include a clear and concise description of the problem, +relevant code or error messages, and steps to reproduce the issue. -If you find a bug in GraphAr, first make sure that you are testing against the [latest version of GraphScope](https://github.com/alibaba/GraphScope/tree/main), -your issue may already have been fixed. If not, search our [issues list](https://github.com/alibaba/GraphScope/issues) -on GitHub in case a similar issue has already been opened. +## Requesting Features -If you get confirmation of your bug, [file a bug issue](https://github.com/alibaba/GraphScope/issues/new?assignees=&labels=&template=bug_report.md&title=%5BBUG%5D+) before starting to code. When submitting an issue, please include a clear and concise description of the problem, any relevant code or error messages, and steps to reproduce the issue. +If you find yourself wishing for a feature that doesn't exist in GraphScope, please open [a feature request issue](https://github.com/alibaba/GraphScope/issues/new?assignees=&labels=&template=feature_request.md&title=) +on GitHub to describe the feature, why it's needed, and how it should work. Other users may share similar needs, +and many of GraphScope's features were added because users saw a need. -## Request Feature +## Improving Documentation -If you find yourself wishing for a feature that doesn't exist in GraphScope, you are probably not alone. -There are bound to be others out there with similar needs. Many of the features that GraphScope has today -have been added because our users saw the need. +A great way to contribute to the project is by improving documentation. If you find any incomplete or inaccurate documentation, +please share your knowledge with the community. -[Open a feature request issue](https://github.com/alibaba/GraphScope/issues/new?assignees=&labels=&template=feature_request.md&title=) on GitHub which describes the feature you would -like to see, why you need it, and how it should work. - -## Improve Documentation - -A great way to contribute to the project is to improve documentation. If you found some docs to be incomplete or inaccurate, share your hard-earned knowledge with the rest of the community. - -Documentation improvements are also a great way to gain some experience with our submission and review process, discussed below, without requiring a lot of local development environment setup. In fact, many documentation-only changes can be made directly in the GitHub web interface by clicking the “edit” button. This will handle making a fork and a pull request for you. +Documentation improvements are also a great way to gain some experience with our submission and review process, discussed below, without requiring a lot of local development environment setup. +In fact, many documentation-only changes can be made directly in the [GraphScope document pages](https://graphscope.io/docs/) by clicking the “Edit On Github” button. This will handle making a fork and a pull request for you. TBF: add a link to how to helping with documentation TBF: add a link to how to build the documentation -## Contributing code and documentation changes +## Contributing Code and Documentation Changes -If you would like to contribute a new feature or a bug fix to GraphScope, -please discuss your idea first on the GitHub issue. If there is no GitHub issue -for your idea, please open one. It may be that somebody is already working on -it, or that there are particular complexities that you should know about before -starting the implementation. There are often a number of ways to fix a problem -and it is important to find the right approach before spending time on a PR -that cannot be merged. +If you would like to contribute a new feature or a bug fix to GraphScope, please first discuss your idea on a GitHub issue. +If there isn't an issue for it, create one. There may be someone already working on it, or it may have particular complexities +that you should be aware of before starting to code. There are often several ways to fix a problem, so it's important to find +the right approach before spending time on a PR that can't be merged. ### Install pre-commit GraphScope use `pre-commit`_ to ensure no secrets are accidentally committed -into the Git repository, you could first install `pre-commit`_ by +into the Git repository. Before contributing, install `pre-commit` by typing: ```bash - $ pip3 install pre-commit +$ pip3 install pre-commit ``` -The configure the necessary pre-commit hooks with +Configure the necessary pre-commit hooks with: ```bash - $ pre-commit install --install-hooks +$ pre-commit install --install-hooks ``` ### Minor Fixes -Any functionality change should have a GitHub issue opened. For minor changes that -affect documentation, you do not need to open up a GitHub issue. Instead you can -prefix the title of your PR with "[MINOR] " if meets the following guidelines: +For minor changes that affect documentation, you don't need to open a GitHub issue. Instead, +add the prefix "[MINOR]" to the title of your PR if it meets the following guidelines: * Grammar, usage and spelling fixes that affect no more than 2 files * Documentation updates affecting no more than 2 files and not more than 500 words. -### Fork & create a branch +### Fork and Create a Branch -You will need to fork the main GraphScope code and clone it to your local machine. See -[github help page](https://help.github.com/articles/fork-a-repo) for help. +Fork the main GraphScope code and clone it to your local machine. See +[GitHub help page](https://help.github.com/articles/fork-a-repo) for help. -Then you need to create a branch with a descriptive name. +Create a branch with a descriptive name. A good branch name would be (where issue #42 is the ticket you're working on): ```bash - $ git checkout -b 42-add-chinese-translations +$ git checkout -b 42-add-chinese-translations ``` -### Get the test suite running +### Get the Test Suite Running -See [how to test](./how_to_test.md) for detail. +See [our how-to guide on testing](./how_to_test.md) for help. -### Implement your fix or feature +### Implement Your Fix or Feature -At this point, you're ready to make your changes! Feel free to ask for help; -everyone is a beginner at first :smile_cat: +At this point, you're ready to make the changes. Feel free to ask for help because everyone is a beginner at first! -### Get the code format & style right +### Get the Code Format and Style Right -Your patch should follow the same conventions & pass the same code quality -checks as the rest of the project. Please follw [the code style guide](code_style_guide.md) to get the code format and style right. +Your patch should follow the same conventions and pass the same code quality checks as the rest of the project. +Follow [our code style guide](./code_style_guide.md) to attain the proper code format and style. -### Submitting your changes +### Submitting Your Changes -See [How to submit pull request](how_to_submit_pr) +See [our guide on how to submit a pull request](./how_to_submit_pr.md). -### Discussing and keeping your Pull Request updated +### Discussing and Keeping Your Pull Request Updated -You will probably get feedback or requests for changes to your pull request. -This is a big part of the submission process so don't be discouraged! -It is a necessary part of the process in order to evaluate whether the changes -are correct and necessary. +You will probably receive feedback or requests for changes to your pull request. +This is big part of the submission process and is necessary to evaluate your changes correctly, +so don't be discouraged! -If a maintainer asks you to "rebase" your PR, they're saying that a lot of code -has changed, and that you need to update your branch so it's easier to merge. - -To learn more about rebasing in Git, there are a lot of [good](http://git-scm.com/book/en/Git-Branching-Rebasing) - [resources](https://help.github.com/en/github/using-git/about-git-rebase), but here's the suggested workflow: +If a maintainer asks you to "rebase" your pull request, it means that a lot of code has changed and +you need to update your branch so it's easier to merge. To learn more about rebasing in Git, refer to the recommended workflow: ```bash - $ git checkout 42-add-chinese-translations - $ git pull --rebase upstream main - $ git push --force-with-lease 42-add-chinese-translations +$ git checkout 42-add-chinese-translations +$ git pull --rebase upstream main +$ git push --force-with-lease 42-add-chinese-translations ``` -Feel free to post a comment in the pull request to ping reviewers if you are awaiting an answer -on something. If you encounter words or acronyms that seem unfamiliar, refer to this [glossary](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/glossary.md). +Feel free to comment in the pull request to ping reviewers if you're awaiting a response. +If you encounter unfamiliar words or acronyms, refer to this [glossary](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/glossary.md). ### Merging a PR (maintainers only) -A PR can only be merged into main by a maintainer if: +A pull request can only be merged into main by a maintainer if: * It is passing CI. -* It has been approved by at least two maintainers. If it was a maintainer who - opened the PR, only one extra approval is needed. -* It has no requested changes. +* At least two maintainers have approved it. If a maintainer opened the PR, only one extra approval is needed. +* There are no requested changes. * It is up to date with current main. -### Shipping a release (maintainers only) +### Shipping a Release (maintainers only) TODO(dongze): TBF @@ -174,11 +160,8 @@ All pull requests that contain changes to code must be run through continuous integration (CI) testing at [Github Actions](https://github.com/alibaba/GarphScope/actions) The pull request change will trigger a CI testing run. Ideally, the code change -will pass ("be green") on all platform configurations supported by GraphAr. +will pass ("be green") on all platform configurations supported by GraphScope. This means that all tests pass and there are no linting errors. In reality, however, it is not uncommon for the CI infrastructure itself to fail on specific platforms ("be red"). It is vital to visually inspect the results of all failed ("red") tests to determine whether the failure was caused by the changes in the pull request. - -[1]: https://github.com/alibaba/GraphScope/blob/main/CODE_OF_CONDUCT.md -