add clang-format and add some info to dev guides

Signed-off-by: fan <yfan3763@gmail.com>
opencurve · Feb 7, 2023 · 3050265 · 3050265
1 parent 1c56c06
commit 3050265
Show file tree

Hide file tree

Showing 6 changed files with 309 additions and 5 deletions.
diff --git a/.clang-format b/.clang-format
@@ -0,0 +1,147 @@
+---
+Language:        Cpp
+AccessModifierOffset: -3
+AlignAfterOpenBracket: Align
+AlignConsecutiveMacros: true
+AlignConsecutiveAssignments: false
+AlignConsecutiveBitFields: false
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Right
+AlignOperands:   Align
+AlignTrailingComments: true
+AllowAllArgumentsOnNextLine: true
+AllowAllConstructorInitializersOnNextLine: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortEnumsOnASingleLine: true
+AllowShortBlocksOnASingleLine: Never
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: All
+AllowShortLambdasOnASingleLine: All
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: MultiLine
+BinPackArguments: true
+BinPackParameters: true
+BraceWrapping:
+  AfterCaseLabel:  false
+  AfterClass:      false
+  AfterControlStatement: Never
+  AfterEnum:       false
+  AfterFunction:   false
+  AfterNamespace:  false
+  AfterObjCDeclaration: false
+  AfterStruct:     false
+  AfterUnion:      false
+  AfterExternBlock: false
+  BeforeCatch:     false
+  BeforeElse:      false
+  BeforeLambdaBody: false
+  BeforeWhile:     false
+  IndentBraces:    false
+  SplitEmptyFunction: true
+  SplitEmptyRecord: true
+  SplitEmptyNamespace: true
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Attach
+BreakBeforeInheritanceComma: false
+BreakInheritanceList: BeforeColon
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: false
+BreakConstructorInitializers: BeforeColon
+BreakAfterJavaFieldAnnotations: false
+BreakStringLiterals: true
+ColumnLimit:     80
+CommentPragmas:  '^ IWYU pragma:'
+CompactNamespaces: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: false
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DeriveLineEnding: true
+DerivePointerAlignment: false
+DisableFormat:   false
+ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: true
+ForEachMacros:
+  - foreach
+  - Q_FOREACH
+  - BOOST_FOREACH
+IncludeBlocks:   Preserve
+IncludeCategories:
+  - Regex:           '^"(llvm|llvm-c|clang|clang-c)/'
+    Priority:        2
+    SortPriority:    0
+  - Regex:           '^(<|"(gtest|gmock|isl|json)/)'
+    Priority:        3
+    SortPriority:    0
+  - Regex:           '.*'
+    Priority:        1
+    SortPriority:    0
+IncludeIsMainRegex: '(Test)?$'
+IncludeIsMainSourceRegex: ''
+IndentCaseLabels: false
+IndentCaseBlocks: false
+IndentGotoLabels: true
+IndentPPDirectives: None
+IndentExternBlock: AfterExternBlock
+IndentWidth:     4
+IndentWrappedFunctionNames: false
+InsertTrailingCommas: None
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: true
+MacroBlockBegin: ''
+MacroBlockEnd:   ''
+MaxEmptyLinesToKeep: 2
+NamespaceIndentation: None
+ObjCBinPackProtocolList: Auto
+ObjCBlockIndentWidth: 2
+ObjCBreakBeforeNestedBlockParam: true
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: true
+PenaltyBreakAssignment: 2
+PenaltyBreakBeforeFirstCallParameter: 19
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 1000
+PenaltyBreakTemplateDeclaration: 10
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 60
+PointerAlignment: Right
+ReflowComments:  true
+SortIncludes:    false
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: false
+SpaceAfterLogicalNot: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: true
+SpaceInEmptyBlock: false
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 2
+SpacesInAngles:  false
+SpacesInConditionalStatement: false
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+SpaceBeforeSquareBrackets: false
+Standard:        Cpp11
+StatementMacros:
+  - Q_UNUSED
+  - QT_REQUIRE_VERSION
+TabWidth:        4
+UseCRLF:         false
+UseTab:          Never
+WhitespaceSensitiveMacros:
+  - STRINGIZE
+  - PP_STRINGIZE
+  - BOOST_PP_STRINGIZE
+...
diff --git a/Community_Guidelines.md → developers_guide.md b/Community_Guidelines.md → developers_guide.md
@@ -87,6 +87,12 @@ If the work to be done is more complicated, you need to write a detailed design
 It is also recommended to communicate with us before starting the plan writing. If you are not sure about the feasibility of the plan, you can provide a simple plan description first, and then refine and develop it after our evaluation.
 
 
+## How to start a document contribution
+
+The curve docs path is in [curve/docs/](https://github.com/opencurve/curve/tree/master/docs), please use markdown format about the docs contribution except ppt.
+
+Document contribution don't need to trigger CI. please add ```[skipci]``` in your github pr title.
+
 ## How to submit a PR
 
 Once you've finished writing the code, you can submit a PR. Of course, if the development has not been completed, you can submit PR first in some cases. For example, if you want to let the community take a look at the general solution, you can raise the price of PR after completing the code framework.
@@ -95,14 +101,45 @@ Once you've finished writing the code, you can submit a PR. Of course, if the de
 
 [Build and run Curve tests](https://github.com/opencurve/curve/blob/master/docs/en/build_and_run_en.md#test-case-compilation-and-execution)
 
+Please use clangd for your code completions. More details is in [curve_clangd.md](https://github.com/opencurve/curve/blob/master/docs/cn/clangd.md).
+
+Curve Ci use ```cpplint``` check what your changed.
+
+- install ``cpplint``` (need root)
+  ```bash
+  $ pip install cpplint
+  ```
+
+- check your changed local
+  ```bash
+  $ cpplint --filter=-build/c++11 --quiet --recursive your_path
+  ```
+
 For PR we have the following requirements:
 
-- The CURVE coding standard strictly follows the [Google C++ Open Source Project Coding Guide](https://google.github.io/styleguide/cppguide.html), please follow this guide as well Submit your code.
+- The CURVE coding standard strictly follows the [Google C++ Open Source Project Coding Guide](https://google.github.io/styleguide/cppguide.html), but we use 4 spaces to indent, Clang-format will more helpful for you. Of course, CI will check what your changed. 
 - The code must have test cases, excluding documentation, unit tests (incremental lines cover more than 80%, and incremental branches cover more than 70%); integration tests (merge statistics with unit tests, and meet the unit test coverage requirements).
 - Please fill in the description of the PR as detailed as possible,  associate with the relevant issues, and the PR commit message can clearly see the resolved issues. After submitting to the Curve master branch, Curve CI will be triggered automatically. It is necessary to ensure that the CI is passed, and the Jenkins username and password of the CI is netease/netease, if the CI fails to run, you can log in to the Jenkins platform to view the reason for the failure.
 - After the CI is passed, the review can start, and each PR needs to get at least two LGTMs of Committer/Maintainer before merging.
 - PR code requires a certain amount of comments to make the code easy to understand, and all comments and review comments and replies are required to be in English.
 
+- Please make sure your changed can pass the compile locally.
+
+- We usually merge only one commit after you rebase.
+
+- Trigger CI please comment ```cicheck```.
+
+  CI checkpoints:
+
+    1. The changed code style check(cpplint).
+    2. Branch test coverage testing.
+    3. Unit tests(If failed, run the failed tests locally).
+    4. Chaos tests.
+
+Repush will trigger CI, If github page have no reaction. Please wait.
+
+If CI is not stabled, comment ```recheck``` will trigger CI.
+
 ## Comminication
 
 At present, the Curve community has multiple communication channels, please choose an appropriate and efficient communication method according to your needs:

diff --git a/Community_Guidelines_cn.md → developers_guide_cn.md b/Community_Guidelines_cn.md → developers_guide_cn.md
@@ -45,6 +45,11 @@ Curve 社区有多个[沟通渠道](#社区交流)，每两周还会有线上的
 
 在开始方案撰写之前同样建议先与我们进行沟通，对方案的可行性不太确定的可以先提供简单的方案描述，经过我们评估后再进行细化和开发。
 
+## 如何进行文档贡献
+
+Curve 的文档位于 [curve/docs/](https://github.com/opencurve/curve/tree/master/docs), 贡献请使用 markdown 格式(除了ppt).
+
+文档贡献无需触发 CI, 请在 github pull request 标题头部加上 ```[skipci]```.
 
 ## 如何提交PR
 
@@ -54,9 +59,21 @@ Curve 社区有多个[沟通渠道](#社区交流)，每两周还会有线上的
 
 [Curve 测试用例编译及执行](https://github.com/opencurve/curve/blob/master/docs/cn/build_and_run.md#测试用例编译及执行)
 
+代码补全: 请使用 clangd 作为代码补全, 请见 [curve_clangd.md](https://github.com/opencurve/curve/blob/master/docs/cn/clangd.md).
+
+Curve CI 使用```cpplint```检查更改的代码,
+- 安装```cpplint``` (需要root):
+  ```bash
+  $ pip install cpplint
+  ```
+- 本地进行代码检查:
+  ```bash
+  $ cpplint --filter=-build/c++11 --quiet --recursive your_path
+  ```
+
 对于 PR 我们有如下要求：
 
-- CURVE编码规范严格按照[Google C++开源项目编码指南](https://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/contents/)来进行代码编写，请您也遵循这一指南来提交您的代码。
+- CURVE编码规范严格按照[Google C++开源项目编码指南](https://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/contents/)来进行代码编写，但使用 4 空格进行缩进, 可使用 clang-format 进行格式化, CI 会检查相关更改代码是否符合规则.
 - 代码必须有测试，文档除外，单元测试（增量行覆盖80%以上，增量分支覆盖70%以上）；集成测试（与单元测试合并统计，满足单元测试覆盖率要求即可）
 - 请尽可能详细的填写 PR 的描述，关联相关问题的 issuse，PR commit message 能清晰看出解决的问题，提交到 Curve master 分支之后会自动触发Curve CI，需保证 CI 通过，CI 的 Jenkins 用户名密码为 netease/netease，如遇到 CI 运行失败可以登录 Jenkins 平台查看失败原因。
 - CI 通过之后可开始进行 review，每个 PR 在合并之前都需要至少得到两个 Committer/Maintainer 的 LGTM。
@@ -102,6 +119,25 @@ type 可以是以下类型之一：
 
 footer 是可选的，用来记录对应因为这些更改而可以关闭的 issue，如 `Close #12345`
 
+提交 PR 之前, 请确保你的更改可以成功在本地编译.
+
+与大多数项目一样, review 通过之后请将你诸多commits rebase 成为一个 commit.
+
+触发 CI 请 comment ```cicheck```.
+
+若发现测试错误, 可查看 CI 对应错误测试.
+
+CI 检查点有:
+
+  1. 更改代码风格检查(cpplint)
+  2. 分支覆盖率检查(可能会失败)
+  3. 单元测试 (若失败请先尝试在本地运行对应失败测试)
+  4. 混沌测试
+
+重新 push 会触发 CI, 若暂时无反应, 请耐心等待, 测试处于排队中.
+
+若 CI 不稳定, 可 comment ```recheck```, 重新触发 CI.
+
 ## 社区交流
 
 目前 Curve 社区有多个沟通交流的渠道，请根据自己的需求选择合适高效的沟通方式：

diff --git a/docs/cn/build_and_run.md b/docs/cn/build_and_run.md
@@ -20,12 +20,16 @@ mk-tar.sh 和 mk-deb.sh 用于 curve v2.0 之前版本的编译打包，v2.0 版
 docker pull opencurvedocker/curve-base:build-debian9
 ```
 
+```bash
+docker pull opencurvedocker/curve-base:build-debian9
+```
+
 方法二：手动构建docker镜像
 
 使用工程目录下的 docker/debian9/compile/Dockerfile 进行构建，命令如下：
 
 ```bash
-docker build -t opencurvedocker/curve-base:build-debian9 .
+docker build -t opencurvedocker/curve-base:build-debian9
 ```
 
 注意：上述操作不建议在CURVE工程目录执行，否则构建镜像时会把当前目录的文件都复制到docker镜像中，建议把Dockerfile拷贝到新建的干净目录下进行docker镜像的构建。
@@ -98,6 +102,44 @@ bazel build test/common:common-test --copt -DHAVE_ZLIB=1 --define=with_glog=true
 
 执行测试前需要先准备好测试用例运行所需的依赖：
 
+运行单元测试:
+- 构建对应的模块测试:
+  ```bash
+  $ bazel build xxx/...//:xxx_test
+  ```
+- 运行对应的模块测试:
+  ```bash
+  $ bazel run xxx/...//:xxx_test
+  # 或者
+  $ ./bazel-bin/xxx/.../xxx_test
+  ```
+- 编译全部测试及文件
+  ```bash
+  $ bazel build "..."
+  ```
+- bazel 默认自带缓存编译, 但有时可能会失效.
+
+  清除项目构建缓存:
+  ```bash
+  $ bazel clean
+  ```
+
+  清除项目依赖缓存(bazel 会将WORKSPACE 文件中的指定依赖项自行编译, 这部分同样也会缓存):
+  ```bash
+  $ bazel clean --expunge
+  ```
+- debug 模式编译(-c 指定向bazel 传递参数), 该模式会在默认构建文件中加入调试符号, 及减少优化等级.
+  ```bash
+  $ bazel build xxx//:xxx_test -c dbg
+  ```
+- 优化模式编译
+  ```bash
+  $ bazel build xxx//:xxx_test -c opt
+  # 优化模式下加入调试符号
+  $ bazel build xxx//:xxx_test -c opt --copt -g
+  ```
+- 更多文档, 详见 [bazel docs](https://bazel.build/docs).
+
 #### 动态库
 
 ```bash

diff --git a/docs/cn/clangd.md b/docs/cn/clangd.md
@@ -11,7 +11,7 @@
    需要把之前手动生成的pb.h/cc文件删除（proto目录、curvefs/proto目录下）
 
    如果没有其他问题，会在工程目录下生成compile_command.json文件
-
+   如果遇到 python 脚本等报错, 请升级 python 版本.
 ## vscode clangd 配置
 
 1. 卸载或禁用ms-vscode.cpptools

diff --git a/docs/en/build_and_run_en.md b/docs/en/build_and_run_en.md
@@ -21,7 +21,7 @@ Method 2: Build docker image manually
 Use the Dockerfile in the project directory to build. The command is as follows:
 
 ```bash
-docker build -t opencurvedocker/curve-base:build-debian9.
+docker build -t opencurvedocker/curve-base:build-debian9
 ```
 
 Note: The above operations are not recommended to be performed in the CURVE project directory, otherwise the files in the current directory will be copied to the docker image when building the image. It is recommended to copy the Dockerfile to the newly created clean directory to build the docker image.
@@ -96,6 +96,48 @@ $    --define=libunwind=true
 
 Before executing the test, you need to prepare the dependencies required for the test case to run:
 
+execute unit tests:
+- build module tests:
+  ```bash
+  $ bazel build xxx/...//:xxx_test
+  ```
+
+- run module tests:
+
+  ```bash
+  $ bazel run xxx/xxx//:xxx_test
+  ```
+
+- compile all tests
+
+  ```bash
+  $ bazel build "..."
+  ```
+
+- sometimes the bazel compiling cache will be failure.
+
+  clean the project cache:
+  ```bash
+  $ bazel clean
+  ```
+
+  clean the project cache and deps cache.(bazel will also save project cache).
+  ```bash
+  $ bazel clean --expunge
+  ```
+
+- debug mode build:
+  ```bash
+  $ bazel build xxx//:xxx_test -c dbg
+  ```
+
+- releases mode build
+  ```bash
+  $ bazel build xxx//:xxx_test -c opt
+  ```
+
+- more about bazel docs, please go [bazel docs](https://bazel.build/docs).
+
 #### Dynamic library
 
 ```bash