Refactor README and docs

README.md

@@ -3,22 +3,58 @@
 
 CURVE是网易自主设计研发的高性能、高可用、高可靠分布式存储系统，具有非常良好的扩展性。基于该存储底座可以打造适用于不同应用场景的存储系统，如块存储、对象存储、云原生数据库等。当前我们基于CURVE已经实现了高性能块存储系统，支持快照克隆和恢复 ,支持QEMU虚拟机和物理机NBD设备两种挂载方式, 在网易内部作为高性能云盘使用。
 
-## 文档
+## 设计文档
 
-- 通过 [简介](https://opencurve.github.io/) 可以了解 curve 架构
-- 通过 [编译与运行](docs/cn/build_and_run.md) 可以了解如何编译和执行单元测试
-- CURVE系列文档
+- 通过 [CURVE概述](https://opencurve.github.io/) 可以了解 CURVE 架构
+- CURVE相关文档
   - [NEBD](docs/cn/nebd.md)
   - [MDS](docs/cn/mds.md)
   - [Chunkserver](docs/cn/chunkserver_design.md)
   - [Snapshotcloneserver](docs/cn/snapshotcloneserver.md)
-  - [Curve质量体系](docs/cn/quality.md)
+  - [CURVE质量体系介绍](docs/cn/quality.md)
 
 ## 快速开始
 
-- 通过 [集群部署](docs/cn/deploy.md) 快速搭建 curve 集群
+在您开始动手部署前请先仔细阅读特别说明部分：[特别说明](docs/cn/deploy.md#%E7%89%B9%E5%88%AB%E8%AF%B4%E6%98%8E)
 
-## 反馈和参与
+### 部署All-in-one体验环境
 
-- bug、疑惑、修改建议都欢迎提在[Github Issues](https://github.com/opencurve/curve/issues)中
-- [FAQ](https://github.com/opencurve/curve/wiki/CURVE-FAQ)
+[单机部署](docs/cn/deploy.md#%E5%8D%95%E6%9C%BA%E9%83%A8%E7%BD%B2)
+
+### 部署多机集群
+
+[多机部署](docs/cn/deploy.md#%E5%A4%9A%E6%9C%BA%E9%83%A8%E7%BD%B2)
+
+
+## 参与开发
+
+
+### 部署编译开发环境
+
+[编译开发环境搭建](docs/cn/build_and_run.md)
+
+### 测试用例编译及运行
+[测试用例编译及运行](docs/cn/build_and_run.md#%E6%B5%8B%E8%AF%95%E7%94%A8%E4%BE%8B%E7%BC%96%E8%AF%91%E5%8F%8A%E6%89%A7%E8%A1%8C)
+
+### 编码规范
+CURVE编码规范严格按照[Google C++开源项目编码指南](https://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/contents/)来进行代码编写，请您也遵循这一指南来提交您的代码。
+
+### 测试覆盖率要求
+1. 单元测试：增量行覆盖80%以上，增量分支覆盖70%以上
+2. 集成测试：与单元测试合并统计，满足上述覆盖率要求即可
+3. 异常测试：暂不做要求
+
+### 其他开发流程说明
+TODO
+
+## 版本发布周期
+- CURVE版本发布周期：大版本半年，小版本1~2个月
+- 版本号规则：采用3段式版本号，x.y.z，x是大版本，y是用来区分开发版本、rc版本、和稳定版本的（对应0、1、2三个数字），z是BugFixes或小的功能版本。每半年的大版本是指x增加1，每1~2个月的小版本是z增加1
+
+## 反馈及交流
+
+- [Github Issues](https://github.com/openCURVE/CURVE/issues)：欢迎提交BUG、建议，使用中如遇到问题可参考FAQ或加入我们的User group进行咨询
+- [FAQ](https://github.com/openCURVE/CURVE/wiki/CURVE-FAQ)：主要根据User group中常见问题整理，还在逐步完善中
+- User group：当前为微信群，由于群人数过多，需要先添加以下个人微信，再邀请进群。
+
+<img src="https://raw.githubusercontent.com/opencurve/opencurve.github.io/master/image/curve-wechat.jpeg" style="zoom: 75%;" />
\ No newline at end of file

docs/cn/build_and_run.md

-# 编译与运行
 
-本文用于了解如何编译和执行单元测试。
+# 编译环境搭建
 
-## 依赖项
+请注意：
+1. 如您只是想体验CURVE的部署流程和基本功能，**则不需要编译CURVE**，请参考[单机部署](docs/cn/deploy.md#%E5%8D%95%E6%9C%BA%E9%83%A8%E7%BD%B2)
+2. 本文档仅用来帮助你搭建CURVE代码编译环境，便于您参与CURVE的开发调试及打包测试
+
+## 使用Docker进行编译（推荐方式）
+
+### 获取或者构建docker镜像
+
+方法一：从docker hub镜像库中拉取docker镜像（推荐方式）
+
+```bash
+docker pull opencurve/curvebuild:centos8
+```
+
+方法二：手动构建docker镜像
+
+使用工程目录下的Dockerfile进行构建，命令如下：
+
+```bash
+docker build -t opencurve/curvebuild:centos8 .
+```
+
+注意：上述操作不建议在curve工程目录执行，否则构建镜像时会把当前目录的文件都复制到docker镜像中，建议把Dockerfile拷贝到新建的干净目录下进行docker镜像的构建。
+
+
+
+### 在docker镜像中编译
+
+```bash
+docker run -it opencurve/curvebuild:centos8 /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 mk-tar.sh
+```
+
+基于tar包的安装部署流程可参考：[集群部署](docs/cn/deploy.md)
+
+## 在物理机上编译
 
 curve编译依赖的包括：
 
@@ -11,49 +48,51 @@ curve编译依赖的包括：
 | bazel | 0.17.2 |
 | gcc   | 支持c++11的兼容版本 |
 
-curve的其他依赖项，均有bazel去管理，可不单独安装。
+curve的其他依赖项，均由bazel去管理，可不单独安装。
 
-## 安装依赖
+### 安装依赖
 
-### Ubuntu/LinuxMint/WSL
+#### Ubuntu/LinuxMint/WSL
 
 ```
 sudo apt-get install -y bazel git g++ make
 ```
 
 
-### Fedora/CentOS
+#### Fedora/CentOS
 
 ```
 sudo yum install bazel git gcc-c++ make
 ```
 
-## 编译
-
 ### 一键编译和打包
 
 opencurve 提供一键编译脚本，mk-tar.sh 生成所需的全部tar二进制包，命令如下：
 
 ```
+# （可选步骤）将外部依赖替换为国内下载点或镜像仓库，可以加快编译速度： bash replace-curve-repo.sh
 bash ./mk-tar.sh
 ```
 
+基于tar包的安装部署流程可参考：[集群部署](docs/cn/deploy.md)
+
 特别的，由于curve内部版本使用在debian系统上，因此特别提供debian的版本，命令如下：
 
 ```
 bash ./mk-deb.sh
 ```
+注意：基于deb包的安装部署流程正在整理中，目前不推荐使用deb包安装部署
 
-### 单独编译和运行模块测试
+## 测试用例编译及执行
 
-#### 编译全部模块
+### 编译全部模块
 
 仅编译全部模块，不进行打包
 ```
 bazel build ... --compilation_mode=dbg -s --collect_code_coverage  --jobs=32 --copt   -DHAVE_ZLIB=1 --define=with_glog=true --define=libunwind=true --copt -DGFLAGS_NS=google --copt -Wno-error=format-security --copt -DUSE_BTHREAD_MUTEX
 ```
 
-#### 编译对应模块的代码和运行测试·
+### 编译对应模块的代码和运行测试
 
 编译对应模块，例如test/common目录下的common-test测试：
 
@@ -61,42 +100,55 @@ bazel build ... --compilation_mode=dbg -s --collect_code_coverage  --jobs=32 --c
 bazel build test/common:common-test --copt -DHAVE_ZLIB=1 --define=with_glog=true --compilation_mode=dbg --define=libunwind=true
 ```
 
-单独运行该测试：
+### 执行测试
 
-```
-./bazel-bin/test/common/common-test
-```
+执行测试前需要先准备好测试用例运行所需的依赖：
 
+#### 动态库
 
-## 使用Docker进行编译
+```bash
+export LD_LIBRARY_PATH=<CURVE-WORKSPACE>/thirdparties/etcdclient:<CURVE-WORKSPACE>/thirdparties/aws-sdk/usr/lib:/usr/local/lib:${LD_LIBRARY_PATH}
+```
 
-### 获取或者构建docker镜像
+#### fake-s3
 
-方法一：从镜像库中拉取docker镜像(推荐方式)
+快照克隆集成测试中，使用了开源的[fake-s3](https://github.com/jubos/fake-s3)模拟真实的s3服务。
 
 ```bash
-docker pull opencurve/curvebuild:centos8
+$ apt install ruby -y OR yum install ruby -y
+$ gem install fakes3
+$ fakes3 -r /S3_DATA_DIR -p 9999 --license YOUR_LICENSE_KEY
 ```
 
-方法二：构建docker镜像
+备注：
 
-使用工程目录下的Dockerfile进行构建，命令如下：
+- `-r S3_DATA_DIR`：存放数据的目录
+- `--license YOUR_LICENSE_KEY`：fakes3需要key才能运行，申请地址见[fake-s3](https://github.com/jubos/fake-s3)
+- `-p 9999`：fake-s3服务启动的端口，**不用更改**
+
+#### etcd
 
 ```bash
-docker build -t opencurve/curvebuild:centos8 .
+wget -ct0 https://github.com/etcd-io/etcd/releases/download/v3.4.10/etcd-v3.4.10-linux-amd64.tar.gz
+tar zxvf etcd-v3.4.10-linux-amd64.tar.gz
+cd etcd-v3.4.10-linux-amd64 && cp etcd etcdctl /usr/bin
 ```
 
-Node：这一步操作最好不要在curve工程目录执行，因为docker构建时，会把当前目录的文件都复制到docker中。
+#### 执行单个测试模块
+```
+./bazel-bin/test/common/common-test
+```
 
+#### 运行单元/集成测试
 
+bazel 编译后的可执行程序都在 `./bazel-bin` 目录下，例如 test/common 目录下的测试代码对应的测试程序为 `./bazel-bin/test/common/common-test`，可以直接运行程序进行测试。
+- curve相关单元测试程序目录在 ./bazel-bin/test 目录下，集成测试在 ./bazel-bin/test/integration 目录下
+- nebd相关单元测试程序在 ./bazel-bin/nebd/test 目录下
+- nbd相关单元测试程序在 ./bazel-bin/nbd/test 目录下
 
-### 在docker镜像中编译
+如果想运行所有的单元测试和集成测试，可以执行工程目录下的ut.sh脚本：
 
 ```bash
-docker run -it opencurve/curvebuild:centos8 /bin/bash
-cd <workspace>
-git clone https://github.com/opencurve/curve.git 或者 git clone https://gitee.com/mirrors/curve.git
-bash mk-tar.sh
+bash ut.sh
 ```
 
-Note：curve使用了一些外部组件，例如etcd、brpc、braft等，在编译时会拉去依赖仓库，这一步骤可能比较耗时。为了加速编译，提供了`replace-curve-repo.sh`，用于替换相关仓库为国内的镜像。

docs/cn/deploy.md

@@ -88,15 +88,19 @@ ansible是一款自动化运维工具，curve-ansible 是基于 ansible playbook
    $ pip install --upgrade setuptools
    ```
 4. 检查其他依赖，未安装的需要手动安装：net-tools, openssl-1.1.1, perf, perl-podlators, make, gcc6.1, libstdc++.so.6.22, libcurl
+
 #### 实施部署
 
 1. 切换到curve用户下执行以下操作
 
-2. 获取tar包并解压。有两种方式：从github下载tar包和自行打包
+2. 获取tar包并解压
 
-   2.1 从github下载tar包，如果想要部署release版本，则从github下载最新的tar包即可。**下面的命令仅供参考，tar包会经常更新，下面给出不一定是最新的**。
+   有两种方式可以获得tar包：
+      1. 从[github release页面](https://github.com/opencurve/curve/releases)下载稳定版本tar包
+      2. 自行通过编译环境打tar包，该方式可以让您体验测试最新代码：[编译开发环境搭建](docs/cn/build_and_run.md)
 
    ```
+   # 如下几个tar包可替换为其他版本（如您采用方式2自行打包，则不需要下载，拷贝相关tar包即可），下载命令仅供参考
    wget https://github.com/opencurve/curve/releases/download/v0.1.1/curve_0.1.1+4b930380.tar.gz
    wget https://github.com/opencurve/curve/releases/download/v0.1.1/nbd_0.1.1+4b930380.tar.gz
    wget https://github.com/opencurve/curve/releases/download/v0.1.1/nebd_0.1.1+4b930380.tar.gz
@@ -105,12 +109,7 @@ ansible是一款自动化运维工具，curve-ansible 是基于 ansible playbook
    tar zxvf nebd_0.1.1+4b930380.tar.gz
    cd curve/curve-ansible
    ```
-   2.2 如果想要部署代码仓库中最新代码的集群，则需要自行打包。打包的步骤为：
-   - cd到本地curve仓库
-   - 执行mk-tar.sh脚本
-   - 解压打出来的curve, nbd, nebd三个tar包
-   - cd curve/curve-ansible
-   
+
 3. 准备inventory文件
    - 在server.ini和client.ini的[all:vars]中增加ansible_connection=local
    - 如果是debian系统，则不需要改动，如果是CentOs系统，需要将client.ini和server.ini中的curve_lib_dir修改为/usr/lib64
@@ -264,11 +263,14 @@ ansible是一款自动化运维工具，curve-ansible 是基于 ansible playbook
 #### 实施部署
 1. 切换到curve用户下执行以下操作
 
-2. 获取tar包并解压。有两种方式：从github下载tar包和自行打包
+2. 获取tar包并解压
 
-   2.1 从github下载tar包，如果想要部署release版本，则从github下载最新的tar包即可。**下面的命令仅供参考，tar包会经常更新，下面给出不一定是最新的**。
+   有两种方式可以获得tar包：
+      1. 从[github release页面](https://github.com/opencurve/curve/releases)下载稳定版本tar包
+      2. 自行通过编译环境打tar包，该方式可以让您体验测试最新代码：[编译开发环境搭建](docs/cn/build_and_run.md)
 
    ```
+   # 如下几个tar包可替换为其他版本（如您采用方式2自行打包，则不需要下载，拷贝相关tar包即可），下载命令仅供参考
    wget https://github.com/opencurve/curve/releases/download/v0.1.1/curve_0.1.1+4b930380.tar.gz
    wget https://github.com/opencurve/curve/releases/download/v0.1.1/nbd_0.1.1+4b930380.tar.gz
    wget https://github.com/opencurve/curve/releases/download/v0.1.1/nebd_0.1.1+4b930380.tar.gz
@@ -277,11 +279,6 @@ ansible是一款自动化运维工具，curve-ansible 是基于 ansible playbook
    tar zxvf nebd_0.1.1+4b930380.tar.gz
    cd curve/curve-ansible
    ```
-   2.2 如果想要部署代码仓库中最新代码的集群，则需要自行打包。打包的步骤为：
-   - cd到本地curve仓库
-   - 执行mk-tar.sh脚本
-   - 解压打出来的curve, nbd, nebd三个tar包
-   - cd curve/curve-ansible
 
 3. 在中控机上修改配置文件
 
@@ -553,4 +550,4 @@ ansible是一款自动化运维工具，curve-ansible 是基于 ansible playbook
       sudo curve-nbd map cbd:pool//test_curve_
    3. 查看设备挂载情况
       curve-nbd list-mapped
-   ```
+   ```
\ No newline at end of file