tisonkun commented on code in PR #107: URL: https://github.com/apache/incubator-kvrocks-website/pull/107#discussion_r1199636584
########## community/contributing.md: ########## @@ -25,47 +26,57 @@ To help you familiarise yourself with the source tree, we have listed some impor /utils/kvrocks2redis C++ source code for the kvrocks2redis tool ``` -Make sure you have C++ (at least GCC >= 7 or Clang >= 5, a higher-version compiler is highly recommended) and Go toolchains in your development environment, referring to the [Getting Started](/docs/getting-started#install-dependencies) page for all build dependencies. -In addition to the source code listed above, the rest of the repository consists mainly of scripts written in python or shell. -And you can read about how to build this project on the [Getting Started](/docs/getting-started#compile-kvrocks-from-source) page. +Make sure you have C++ (at least GCC >= 7 or Clang >= 5, a higher-version compiler is highly recommended) and Go toolchains in your development environment, referring to the [Getting Started](/docs/getting-started#install-dependencies) page for all build dependencies. Then, you can read about how to build this project on the [Getting Started](/docs/getting-started#compile-kvrocks-from-source) page. + +In addition to the source code listed above, the rest of the repository consists mainly of scripts written in Python. + +### Code style + +If your patch contains changes to C++ code, make sure you format the code using Clang Format (`./x.py format` to quickly format all code). In addition, after you submit your patch, the CI (currently [GitHub Actions](https://github.com/apache/incubator-kvrocks/actions)) will perform some checks using Clang Tidy to ensure that the code follows some good patterns (modern C++) and without some security issues. So if the CI reports a problem, you can check the CI logs or run Clang Tidy locally (`./x.py check tidy`) to help you fix your code. And if your patch involves changes to Golang code, make sure you run golangci-lint (`./x.py check golangci-lint`) before submitting the patch. + +### Tests + +For any code changes, we encourage you to add test cases for your changes (C++ unit tests or Go test cases, which are mandatory for large patches) and make sure they all pass before submitting. + +You can use `./x.py test cpp` and `./x.py test go` to run all test cases. -If your patch contains changes to C++ code, make sure you format the code using Clang Format (`./x.py format` to quickly format all code). -In addition, after you submit your patch, the CI (currently [GitHub Actions](https://github.com/apache/incubator-kvrocks/actions)) will perform some checks using Clang Tidy to ensure that the code follows some good patterns (modern C++) and without some security issues. -So if the CI reports a problem, you can check the CI logs or run Clang Tidy locally (`./x.py check tidy`) to help you fix your code. -And if your patch involves changes to Go code, make sure you run golangci-lint (`./x.py check golangci-lint`) before submitting the patch. +You can use `./x.py test cpp <BUILD_DIR> --gtest_filter=<PATTERN>` to run C++ unit tests whose name match the pattern. Technically, all arguments after `<BUILD_DIR>` will be appended to the `unittest` executable. Refer to the [Advanced GoogleTest Topic](http://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests) page for all possible flags. -For any code changes, we encourage you to add test cases for your changes (C++ unit tests or Go test cases, which are mandatory for large patches) and make sure they all pass before submitting (you can use `./x.py test cpp` and `./x.py test go` to run all test cases). +You can use `./x.py test go <BUILD_DIR> -run <PATTERN>` to run Golang test cases whose name match the pattern. Technically, all arguments after `<BUILD_DIR>` will be appended to the `go test` command. Refer to the [testflag](https://pkg.go.dev/cmd/go/internal/test) page for all possible flags. -After opening your pull request (PR), you can choose some reviewers, although it is not mandatory. -We suggest you to choose a reviewer recommended by GitHub based on code snippets you modified, or some active community members (which can be found in the [Community](index.md#people) page). -After one or more committers have approved your PR and the rest of the community has no objections, congratulations, your PR will be merged into the main branch as soon as possible. +After opening your pull request (PR), you can choose some reviewers, although it is not mandatory. We suggest you to choose a reviewer recommended by GitHub based on code snippets you modified, or some active community members (which can be found in the [Community](index.md#people) page). After one or more committers have approved your PR and the rest of the community has no objections, congratulations, your PR will be merged into the unstable branch as soon as possible. ## Submit patches to document or project website Contributions to the documentation and the project website are strongly encouraged, as they are often much less frequent. -The source code for both can be found in [apache/incubator-kvrocks-website](https://github.com/apache/incubator-kvrocks-website) repository, with the documentation written in Markdown format and the website based on Docusaurus. + +The source code for both can be found in [apache/incubator-kvrocks-website](https://github.com/apache/incubator-kvrocks-website) repository, with the documentation written in Markdown format and the website based on Docusaurus. + When contributing to the documentation, it is important to note that: -- Currently, the website does not provide documentation for individual releases, only for code in the main branch of the kvrocks repository, so please be careful not to document behaviour specific to older releases when contributing (if you need to do so, please mark the release separately to avoid confusion). + +- Currently, the website does not provide documentation for individual releases, only for code in the unstable branch of the kvrocks repository, so please be careful not to document behaviour specific to older releases when contributing (if you need to do so, please mark the release separately to avoid confusion). - After making major changes to the documentation, we recommend that you preview the changed version locally first to avoid formatting errors; you can use `yarn start` to build and preview the page locally. - Do not copy from other copyrighted documents. ## Find tasks and start to contribute A major obstacle for people just starting out and wanting to get involved in the community can be the difficulty of knowing where to start. + To solve this problem, here are some suggestions to help new contributors start with simple tasks to learn the structure of the code and participate in the community step by step: + - Filter the [Issues](https://github.com/apache/incubator-kvrocks/issues) with `good first issue` or `help wanted` label, pick a task from there, and get involved. Note that `good first issue` indicates an easy task for newcomers, while `help wanted` has no fixed task difficulty. - Check out the Kvrocks roadmap in [Projects](https://github.com/apache/incubator-kvrocks/projects/2) and [Discussions](https://github.com/apache/incubator-kvrocks/discussions) and pick the parts you are familiar with to contribute. - Keep up to date with Redis developments and feel free to contribute any features that exist in Redis and are missing in Kvrocks. ## Participate in the community and become a committer -As you find tasks to start participating in the community, you will gradually learn about the workings and practices of the community. -Here are some tips to help you feel more comfortable in the community: +As you find tasks to start participating in the community, you will gradually learn about the workings and practices of the community. Here are some tips to help you feel more comfortable in the community: + - Try to express your intentions in as many words as possible, and do not be afraid of words. - Talk to other members to get support before starting a new idea. -After being involved in the community for a while, some members may want to learn how to become a committer, who has write access to the project (this is limited to merging PRs that have been approved and passed the CI, as kvrocks protects the main branch), and the ability to review PRs from others. +After being involved in the community for a while, some members may want to learn how to become a committer, who has write access to the project (this is limited to merging PRs that have been approved and passed the CI, as kvrocks protects the unstable branch), and the ability to review PRs from others. Review Comment: ```suggestion After being involved in the community for a while, some members may want to learn how to become a committer, who has write access to the project (this is limited to merging PRs that have been approved and passed the CI), and the ability to review PRs from others. ``` ########## community/contributing.md: ########## @@ -25,47 +26,57 @@ To help you familiarise yourself with the source tree, we have listed some impor /utils/kvrocks2redis C++ source code for the kvrocks2redis tool ``` -Make sure you have C++ (at least GCC >= 7 or Clang >= 5, a higher-version compiler is highly recommended) and Go toolchains in your development environment, referring to the [Getting Started](/docs/getting-started#install-dependencies) page for all build dependencies. -In addition to the source code listed above, the rest of the repository consists mainly of scripts written in python or shell. -And you can read about how to build this project on the [Getting Started](/docs/getting-started#compile-kvrocks-from-source) page. +Make sure you have C++ (at least GCC >= 7 or Clang >= 5, a higher-version compiler is highly recommended) and Go toolchains in your development environment, referring to the [Getting Started](/docs/getting-started#install-dependencies) page for all build dependencies. Then, you can read about how to build this project on the [Getting Started](/docs/getting-started#compile-kvrocks-from-source) page. + +In addition to the source code listed above, the rest of the repository consists mainly of scripts written in Python. + +### Code style + +If your patch contains changes to C++ code, make sure you format the code using Clang Format (`./x.py format` to quickly format all code). In addition, after you submit your patch, the CI (currently [GitHub Actions](https://github.com/apache/incubator-kvrocks/actions)) will perform some checks using Clang Tidy to ensure that the code follows some good patterns (modern C++) and without some security issues. So if the CI reports a problem, you can check the CI logs or run Clang Tidy locally (`./x.py check tidy`) to help you fix your code. And if your patch involves changes to Golang code, make sure you run golangci-lint (`./x.py check golangci-lint`) before submitting the patch. + +### Tests + +For any code changes, we encourage you to add test cases for your changes (C++ unit tests or Go test cases, which are mandatory for large patches) and make sure they all pass before submitting. + +You can use `./x.py test cpp` and `./x.py test go` to run all test cases. -If your patch contains changes to C++ code, make sure you format the code using Clang Format (`./x.py format` to quickly format all code). -In addition, after you submit your patch, the CI (currently [GitHub Actions](https://github.com/apache/incubator-kvrocks/actions)) will perform some checks using Clang Tidy to ensure that the code follows some good patterns (modern C++) and without some security issues. -So if the CI reports a problem, you can check the CI logs or run Clang Tidy locally (`./x.py check tidy`) to help you fix your code. -And if your patch involves changes to Go code, make sure you run golangci-lint (`./x.py check golangci-lint`) before submitting the patch. +You can use `./x.py test cpp <BUILD_DIR> --gtest_filter=<PATTERN>` to run C++ unit tests whose name match the pattern. Technically, all arguments after `<BUILD_DIR>` will be appended to the `unittest` executable. Refer to the [Advanced GoogleTest Topic](http://google.github.io/googletest/advanced.html#running-a-subset-of-the-tests) page for all possible flags. -For any code changes, we encourage you to add test cases for your changes (C++ unit tests or Go test cases, which are mandatory for large patches) and make sure they all pass before submitting (you can use `./x.py test cpp` and `./x.py test go` to run all test cases). +You can use `./x.py test go <BUILD_DIR> -run <PATTERN>` to run Golang test cases whose name match the pattern. Technically, all arguments after `<BUILD_DIR>` will be appended to the `go test` command. Refer to the [testflag](https://pkg.go.dev/cmd/go/internal/test) page for all possible flags. -After opening your pull request (PR), you can choose some reviewers, although it is not mandatory. -We suggest you to choose a reviewer recommended by GitHub based on code snippets you modified, or some active community members (which can be found in the [Community](index.md#people) page). -After one or more committers have approved your PR and the rest of the community has no objections, congratulations, your PR will be merged into the main branch as soon as possible. +After opening your pull request (PR), you can choose some reviewers, although it is not mandatory. We suggest you to choose a reviewer recommended by GitHub based on code snippets you modified, or some active community members (which can be found in the [Community](index.md#people) page). After one or more committers have approved your PR and the rest of the community has no objections, congratulations, your PR will be merged into the unstable branch as soon as possible. ## Submit patches to document or project website Contributions to the documentation and the project website are strongly encouraged, as they are often much less frequent. -The source code for both can be found in [apache/incubator-kvrocks-website](https://github.com/apache/incubator-kvrocks-website) repository, with the documentation written in Markdown format and the website based on Docusaurus. + +The source code for both can be found in [apache/incubator-kvrocks-website](https://github.com/apache/incubator-kvrocks-website) repository, with the documentation written in Markdown format and the website based on Docusaurus. + When contributing to the documentation, it is important to note that: -- Currently, the website does not provide documentation for individual releases, only for code in the main branch of the kvrocks repository, so please be careful not to document behaviour specific to older releases when contributing (if you need to do so, please mark the release separately to avoid confusion). + +- Currently, the website does not provide documentation for individual releases, only for code in the unstable branch of the kvrocks repository, so please be careful not to document behaviour specific to older releases when contributing (if you need to do so, please mark the release separately to avoid confusion). - After making major changes to the documentation, we recommend that you preview the changed version locally first to avoid formatting errors; you can use `yarn start` to build and preview the page locally. - Do not copy from other copyrighted documents. ## Find tasks and start to contribute A major obstacle for people just starting out and wanting to get involved in the community can be the difficulty of knowing where to start. + To solve this problem, here are some suggestions to help new contributors start with simple tasks to learn the structure of the code and participate in the community step by step: + - Filter the [Issues](https://github.com/apache/incubator-kvrocks/issues) with `good first issue` or `help wanted` label, pick a task from there, and get involved. Note that `good first issue` indicates an easy task for newcomers, while `help wanted` has no fixed task difficulty. - Check out the Kvrocks roadmap in [Projects](https://github.com/apache/incubator-kvrocks/projects/2) and [Discussions](https://github.com/apache/incubator-kvrocks/discussions) and pick the parts you are familiar with to contribute. - Keep up to date with Redis developments and feel free to contribute any features that exist in Redis and are missing in Kvrocks. ## Participate in the community and become a committer -As you find tasks to start participating in the community, you will gradually learn about the workings and practices of the community. -Here are some tips to help you feel more comfortable in the community: +As you find tasks to start participating in the community, you will gradually learn about the workings and practices of the community. Here are some tips to help you feel more comfortable in the community: + - Try to express your intentions in as many words as possible, and do not be afraid of words. - Talk to other members to get support before starting a new idea. -After being involved in the community for a while, some members may want to learn how to become a committer, who has write access to the project (this is limited to merging PRs that have been approved and passed the CI, as kvrocks protects the main branch), and the ability to review PRs from others. +After being involved in the community for a while, some members may want to learn how to become a committer, who has write access to the project (this is limited to merging PRs that have been approved and passed the CI, as kvrocks protects the unstable branch), and the ability to review PRs from others. Review Comment: We can even simplify the sentence :D -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
