Skip to content

Commit

Permalink
docs: make build and contribute guide more friendly
Browse files Browse the repository at this point in the history
Signed-off-by: Ziy1-Tan <ajb459684460@gmail.com>
  • Loading branch information
Ziy1-Tan authored and wuhongsong committed Apr 10, 2023
1 parent 76cb316 commit 15e6952
Show file tree
Hide file tree
Showing 6 changed files with 68 additions and 53 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ Curve supports deployment in private and public cloud environments, and can also
<div align=center> <image src="docs/images/Curve-deploy-on-premises-idc.png" width=60%>
<div align=left>

One of them, CurveFS shared file storage system, can be elasticly scaled to public cloud storage, which can provide users with greater capacity elasticity, lower cost, and better performance experience.
One of them, CurveFS shared file storage system, can be elastically scaled to public cloud storage, which can provide users with greater capacity elasticity, lower cost, and better performance experience.

</details>

Expand Down
12 changes: 6 additions & 6 deletions developers_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,15 +18,15 @@ The premise of participating in an open source project is to understand it, espe

Through the study of the above materials, I believe that you already have an overall understanding of the Curve project, and there may also be some curiosity and doubts. At this time, you can deploy a Curve experience environment, which is conducive to a more intuitive perception of the Curve system. If you encounter a problem or want a new feature, you can track the relevant code. In the process, it is easy to understand the relevant modules. This is lots of contributors completed their first contributions.

The Curve community has multiple [communication channels](#Comminication), and there will be an online community meeting every two weeks. The regular meeting will synchronize the recent progress of the Curve project and answer your questions. You are also welcome to participate in the Curve community regular meeting. We will communicate at the meeting, so that we can quickly answer your questions, improve our understanding of the Curve project and synchronize what we are doing at this stage.
The Curve community has multiple [communication channels](#Communication), and there will be an online community meeting every two weeks. The regular meeting will synchronize the recent progress of the Curve project and answer your questions. You are also welcome to participate in the Curve community regular meeting. We will communicate at the meeting, so that we can quickly answer your questions, improve our understanding of the Curve project and synchronize what we are doing at this stage.

## How to participate in Curve

After you have a certain understanding of the Curve project, if you are interested, you can choose the starting point to participate in the Curve. You can choose from the following aspects:

- Start by selecting a interested one from the [Issues](https://github.com/opencurve/curve/issues) of the Curve project. You can pay attention to issues with the good_first_issue tag which we have assessed as relatively good starters.
- Start by selecting a interested one from the [issues](https://github.com/opencurve/curve/issues) of the Curve project. You can pay attention to issues with the [good first issue](https://github.com/opencurve/curve/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22) tag which we have assessed as relatively good starters.
- Based on a certain understanding of the Curve project, you can also choose from [Roadmap](https://github.com/opencurve/curve/wiki/Roadmap).
- Selecting form [Issues](https://github.com/opencurve/curveadm/issues) and [Roadmap](https://github.com/opencurve/curveadm/issues/92) of Curve Operation and maintenance tools [Curveadm](https://github.com/opencurve/curveadm). Here are [quick start guidelines](https://github.com/opencurve/curveadm/wiki/develop)
- Selecting form [issues](https://github.com/opencurve/curveadm/issues) and [Roadmap](https://github.com/opencurve/curveadm/issues/92) of Curve Operation and maintenance tools [Curveadm](https://github.com/opencurve/curveadm). Here are [quick start guidelines](https://github.com/opencurve/curveadm/wiki/develop)
- In addition to the existing issues, you are also welcome to submit issues that you have discovered or new features you hope for and resolve them.
- You can pay attention to the *TODO* in the existing Curve code, most of which are code logic optimization and features to be supplemented, choose the ones you are interested in and raise relevant issues to follow up and try to solve.

Expand Down Expand Up @@ -117,7 +117,7 @@ Curve Ci use ```cpplint``` check what your changed.

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), but we use 4 spaces to indent, Clang-format will more helpful for you. Of course, CI will check what your changed.
- 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.
Expand All @@ -140,7 +140,7 @@ Repush will trigger CI, If github page have no reaction. Please wait.

If CI is not stabled, comment ```recheck``` will trigger CI.

## Comminication
## Communication

At present, the Curve community has multiple communication channels, please choose an appropriate and efficient communication method according to your needs:

Expand All @@ -151,4 +151,4 @@ At present, the Curve community has multiple communication channels, please choo
- **slack**: cloud-native.slack.com,channel #project_curve
- **Curve User Group**: In order to facilitate instant communication with everyone, the Curve User Group is currently a WeChat group. Due to the large number of people in the group, it is necessary to add OpenCurve_bot WeChat first, and then invite into the group. In the user group, everyone can freely communicate about Curve and storage-related topics, and get immediate feedback on problems.

<img src="docs/images/curve-wechat.jpeg" style="zoom: 75%;" />
<img src="docs/images/curve-wechat.jpeg" style="zoom: 75%;" />
10 changes: 5 additions & 5 deletions developers_guide_cn.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,9 @@ Curve 社区有多个[沟通渠道](#社区交流),每两周还会有线上的

在对 Curve 项目有一定了解后,如果感兴趣就可以选择入手点进行 Curve 开源项目的参与了,可以从以下几个方面进行选择:

- 从 Curve 项目的 [Issue](https://github.com/opencurve/curve/issues) 中选择感兴趣的问题入手,可以特别关注带有 good_first_issue tag 的 issue,这些是我们经过评估认为是相对好入门的一些问题。
- 从 Curve 项目的 [issue](https://github.com/opencurve/curve/issues) 中选择感兴趣的问题入手,可以特别关注带有 [good first issue](https://github.com/opencurve/curve/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3A%22good+first+issue%22) tag 的 issue,这些是我们经过评估认为是相对好入门的一些问题。
- 在对 Curve 项目有一定了解的基础上也可以从 [Roadmap](https://github.com/opencurve/curve/wiki/Roadmap_CN) 中进行选择。
- 从 Curve 项目的运维工具 [Curveadm](https://github.com/opencurve/curveadm)[Issue](https://github.com/opencurve/curveadm/issues)[Roadmap](https://github.com/opencurve/curveadm/issues/92) 中进行选择,开发方式可参见[快速上手 CurveAdm 开发](https://github.com/opencurve/curveadm/wiki/develop)
- 从 Curve 项目的运维工具 [Curveadm](https://github.com/opencurve/curveadm)[issue](https://github.com/opencurve/curveadm/issues)[Roadmap](https://github.com/opencurve/curveadm/issues/92) 中进行选择,开发方式可参见 [快速上手 CurveAdm 开发](https://github.com/opencurve/curveadm/wiki/develop)
- 除了已有的 issue,也欢迎将自己发现的问题或希望的新特性提出 issue 并进行解决。
- 可以关注现有 Curve 代码中的 *TODO* ,大部分为代码逻辑优化和待补充特性,选择感兴趣的提出相关 issue 跟进并尝试解决。

Expand Down Expand Up @@ -73,9 +73,9 @@ Curve CI 使用```cpplint```检查更改的代码,

对于 PR 我们有如下要求:

- CURVE编码规范严格按照[Google C++开源项目编码指南](https://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/contents/)来进行代码编写,但使用 4 空格进行缩进, 可使用 clang-format 进行格式化, CI 会检查相关更改代码是否符合规则.
- 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 平台查看失败原因。
- 请尽可能详细的填写 PR 的描述,关联相关问题的 issue,PR commit message 能清晰看出解决的问题,提交到 Curve master 分支之后会自动触发Curve CI,需保证 CI 通过,CI 的 Jenkins 用户名密码为 netease/netease,如遇到 CI 运行失败可以登录 Jenkins 平台查看失败原因。
- CI 通过之后可开始进行 review,每个 PR 在合并之前都需要至少得到两个 Committer/Maintainer 的 LGTM。
- PR 代码需要一定量的注释来使代码容易理解,且所有注释和 review 意见和回复均要求使用英语。

Expand Down Expand Up @@ -149,4 +149,4 @@ CI 检查点有:
- **slack**: cloud-native.slack.com,channel #project_curve
- **Curve User Group**: 为了便于大家即时的沟通,Curve User Group 目前为微信群,由于群人数过多,需要先添加OpenCurve_bot微信,再邀请进群。在用户群里大家可以自由的沟通关于 Curve 和存储相关的话题,对于存在问题也可以较为即时的得到反馈。

<img src="docs/images/curve-wechat.jpeg" style="zoom: 75%;" />
<img src="docs/images/curve-wechat.jpeg" style="zoom: 75%;" />
50 changes: 27 additions & 23 deletions docs/cn/build_and_run.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,10 @@

# 编译环境搭建

请注意:
1. 如您只是想体验CURVE的部署流程和基本功能,**则不需要编译CURVE**,请参考[部署](https://github.com/opencurve/curveadm/wiki)
2. 本文档仅用来帮助你搭建CURVE代码编译环境,便于您参与CURVE的开发调试
**请注意:**

**注意:**

mk-tar.sh 和 mk-deb.sh 用于 curve v2.0 之前版本的编译打包,v2.0 版本之后不再维护。
1. 如您只是想体验Curve的部署流程和基本功能,**则不需要编译Curve**,请参考 [部署](https://github.com/opencurve/curveadm/wiki)
2. 本文档仅用来帮助你搭建Curve代码编译环境,便于您参与Curve的开发调试

## 使用Docker进行编译(推荐方式)

Expand All @@ -20,10 +17,6 @@ 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 进行构建,命令如下:
Expand All @@ -32,36 +25,37 @@ docker pull opencurvedocker/curve-base:build-debian9
docker build -t opencurvedocker/curve-base:build-debian9
```

注意:上述操作不建议在CURVE工程目录执行,否则构建镜像时会把当前目录的文件都复制到docker镜像中,建议把Dockerfile拷贝到新建的干净目录下进行docker镜像的构建。
**注意:** 上述操作不建议在Curve工程目录执行,否则构建镜像时会把当前目录的文件都复制到docker镜像中,建议把Dockerfile拷贝到新建的干净目录下进行docker镜像的构建。

### 在docker镜像中编译

```bash
docker run -it opencurvedocker/curve-base:build-debian9 /bin/bash
cd <workspace>
git clone https://github.com/opencurve/curve.git 或者 git clone https://gitee.com/mirrors/curve.git
#可选步骤)将外部依赖替换为国内下载点或镜像仓库,可以加快编译速度: bash replace-curve-repo.sh
#中国大陆可选)将外部依赖替换为国内下载点或镜像仓库,可以加快编译速度: bash replace-curve-repo.sh
# curve v2.0 之前
bash mk-tar.sh (编译 curvebs 并打tar包)
bash mk-deb.sh (编译 curvebs 并打debian包)
# curve v2.0 及之后
# (当前)curve v2.0 及之后
编译 curvebs: cd curve && make build stor=bs dep=1
编译 curvefs: cd curve && make build stor=fs dep=1
```

**注意:** `mk-tar.sh``mk-deb.sh` 用于 curve v2.0 之前版本的编译打包,v2.0 版本之后不再维护。

## 在物理机上编译

CURVE编译依赖的包括
Curve编译依赖的包括

| 依赖 | 版本 |
|:-- |:-- |
| bazel | 4.2.2 |
| gcc | 支持c++11的兼容版本 |

CURVE的其他依赖项,均由bazel去管理,不可单独安装。
Curve的其他依赖项,均由bazel去管理,不可单独安装。

**注意** 4.* 版本的 bazel 均可以成功编译 curve 项目,其他版本不兼容。
**注意** 4.* 版本的 bazel 均可以成功编译 Curve 项目,其他版本不兼容。
4.2.2 为推荐版本。

### 安装依赖
Expand All @@ -70,13 +64,13 @@ CURVE的其他依赖项,均由bazel去管理,不可单独安装。

### 一键编译

```
```bash
git clone https://github.com/opencurve/curve.git 或者 git clone https://gitee.com/mirrors/curve.git
# (可选步骤)将外部依赖替换为国内下载点或镜像仓库,可以加快编译速度: bash replace-curve-repo.sh
#中国大陆可选)将外部依赖替换为国内下载点或镜像仓库,可以加快下载速度: bash replace-curve-repo.sh
# curve v2.0 之前
bash mk-tar.sh (编译 curvebs 并打tar包)
bash mk-deb.sh (编译 curvebs 并打debian包)
# curve v2.0 及之后
# (当前)curve v2.0 及之后
编译 curvebs: cd curve && make build stor=bs dep=1
编译 curvefs: cd curve && make build stor=fs dep=1
```
Expand All @@ -86,15 +80,24 @@ bash mk-deb.sh (编译 curvebs 并打debian包)
### 编译全部模块

仅编译全部模块,不进行打包
```
```bash
bash ./build.sh
```

### 编译对应模块的代码和运行测试
### 列出所有测试模块

```bash
# curvebs
bazel query '//test/...'
# curvefs
bazel query '//curvefs/test/...'
```

### 编译对应模块的代码

编译对应模块,例如test/common目录下的common-test测试:

```
```bash
bazel build test/common:common-test --copt -DHAVE_ZLIB=1 --define=with_glog=true --compilation_mode=dbg --define=libunwind=true
```

Expand Down Expand Up @@ -171,7 +174,8 @@ cd etcd-v3.4.10-linux-amd64 && cp etcd etcdctl /usr/bin
```

#### 执行单个测试模块
```

```bash
./bazel-bin/test/common/common-test
```

Expand Down
8 changes: 4 additions & 4 deletions docs/cn/gmock.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@
+ 第6行WillOnce(action)是定义一次调用时所产生的行为,比如定义该方法返回怎么样的值等等。
+ 第7行WillRepeatedly(action)的意思是缺省/重复行为。

## Machers(匹配器)
## Matchers(匹配器)

Matcher用于定义Mock类中的方法的形参的值(当然,如果你的方法不需要形参时,可以保持match为空)。

Expand Down Expand Up @@ -179,7 +179,7 @@ Matcher可以在ON_CALL() or EXPECT_CALL()内部使用,也可以直接判断
| ContainerEq(container) | 类型Eq(container),就是输出结果有点不一样,这里输出结果会带上哪些个元素不被包含在另一个容器中 |
| Pointwise(m, container) | |

所有这些Machers都在命名空间::testing中,使用时需引入这一命名空间
所有这些Matchers都在命名空间::testing中,使用时需引入这一命名空间
例:

using ::testing::Ge;
Expand All @@ -197,7 +197,7 @@ Matcher可以在ON_CALL() or EXPECT_CALL()内部使用,也可以直接判断

| Field(&class::field, m) | argument.field (或 argument->field, 当argument是一个指针时)与匹配器m匹配, 这里的argument是一个class类的实例. |
|:----------------------|:----------------------|
| Key(e) | 容器的key值符合e,e可以是一个值或者是一个Macher |
| Key(e) | 容器的key值符合e,e可以是一个值或者是一个Matcher |
| Pair(m1, m2) | argument是一个std::pair,并且argument.first等于m1,argument.second等于m2. |
| Property(&class::property, m) | argument.property()(或argument->property(),当argument是一个指针时)与匹配器m匹配, 这里的argument是一个class类的实例. |

Expand Down Expand Up @@ -292,7 +292,7 @@ Side Effects 指的是这个action还将对测试起的作用,比如给指针

| Invoke(f) | 使用模拟函数的参数调用f, 这里的f可以是全局/静态函数或函数对象. |
|:-------------------------|:----------------------|
| Invoke(object_pointer, &class::method) | 使用模拟函数的参数调用object_pointer对象的mothod方法. |
| Invoke(object_pointer, &class::method) | 使用模拟函数的参数调用object_pointer对象的method方法. |

### 复合动作

Expand Down
Loading

0 comments on commit 15e6952

Please sign in to comment.