You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by wu...@apache.org on 2018/12/28 14:23:13 UTC
[incubator-skywalking] branch master updated: guides cn md (#2096)
This is an automated email from the ASF dual-hosted git repository.
wusheng pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-skywalking.git
The following commit(s) were added to refs/heads/master by this push:
new 15188e5 guides cn md (#2096)
15188e5 is described below
commit 15188e5dd77855ab88b902e2806fd74c5d63aced
Author: 于玉桔 <76...@qq.com>
AuthorDate: Fri Dec 28 22:23:05 2018 +0800
guides cn md (#2096)
---
.../others/cn/guides/Component-library-settings.md | 62 ++++
docs/others/cn/guides/How-to-build.md | 106 ++++++
docs/others/cn/guides/How-to-release.md | 377 +++++++++++++++++++++
.../cn/guides/Java-Plugin-Development-Guide.md | 299 ++++++++++++++++
docs/others/cn/guides/README.md | 45 ++-
docs/others/cn/guides/backend-oal-scripts.md | 11 +
docs/others/cn/guides/storage-extention.md | 41 +++
docs/others/cn/guides/write-oal.md | 15 +
8 files changed, 954 insertions(+), 2 deletions(-)
diff --git a/docs/others/cn/guides/Component-library-settings.md b/docs/others/cn/guides/Component-library-settings.md
new file mode 100644
index 0000000..16806b0
--- /dev/null
+++ b/docs/others/cn/guides/Component-library-settings.md
@@ -0,0 +1,62 @@
+# 组件库设置
+组件库设置与受监视应用程序中使用的您自己或第三方库有关。
+
+在 agent 或 SDK 中, 无论将库名称收集为ID或String（简单地说，例如SpringMVC），收集器格式化ID中的数据，以获得更好的性能和更少的存储要。
+
+此外，收集器根据组件库推测远程服务，例如：
+组件库是MySQL驱动程序库，那么远程服务应该是MySQL Server。
+
+出于这两个原因，收集器需要此文件中的两部分设置：
+
+1.组件库ID，名称和语言。
+1.远程服务器映射，基于本地库。
+
+**必须在此文件中定义所有组件名称和ID。**
+
+## 组件库ID
+定义受监视应用程序中使用的所有组件库的名称和ID。
+这是双向映射，agent或SDK可以value（ID）来表示上行链路数据中的组件名称。
+
+- Name：agent和UI中使用的组件名称
+- id：唯一ID。 一旦发布，所有ID都会被保留。
+- languages：程序语言可以使用此组件。 多语言应该用`，`分隔
+
+### ID 规则
+- Java and 多语言共享: (0, 3000]
+- .NET 平台使用: (3000, 4000]
+- Node.js 平台使用: (4000, 5000]
+- Go 平台使用: (5000, 6000]
+- PHP 平台使用: (6000, 7000]
+- Python 使用: (7000, 8000]
+
+实例
+```yaml
+Tomcat:
+ id: 1
+ languages: Java
+HttpClient:
+ id: 2
+ languages: Java,C#,Node.js
+Dubbo:
+ id: 3
+ languages: Java
+H2:
+ id: 4
+ languages: Java
+```
+
+## 远端服务映射
+远端服务器根据本地组件推断而出，映射基于组件库名称.
+
+- Key: 客户端组件库名称
+- Value: 服务组件名称
+
+```yaml
+Component-Server-Mappings:
+ Jedis: Redis
+ StackExchange.Redis: Redis
+ SqlClient: SqlServer
+ Npgsql: PostgreSQL
+ MySqlConnector: Mysql
+ EntityFrameworkCore.InMemory: InMemoryDatabase
+```
\ No newline at end of file
diff --git a/docs/others/cn/guides/How-to-build.md b/docs/others/cn/guides/How-to-build.md
new file mode 100644
index 0000000..65cb6e0
--- /dev/null
+++ b/docs/others/cn/guides/How-to-build.md
@@ -0,0 +1,106 @@
+# 编译指南
+本文档会介绍Skywalking在maven和您使用的IDE下如何进行编译和构建.
+
+## 项目构建
+**因为我们使用了`Git submodule`，所以我们建议不要使用`GitHub`标签或发布页面来下载用于编译的源代码。**
+
+### 从GitHub代码构建
+1. 准备git、JDK8和maven3。
+1. `git clone https://github.com/apache/incubator-skywalking.git`
+1. `cd incubator-skywalking/`
+1. 使用`git checkout [tagname]`切换对应的标签代码版本(可选项，如果要从源代码构建版本，则切换）
+1. `git submodule init`
+1. `git submodule update`
+1. 运行 `./mvnw clean package -DskipTests`
+1. 打包后的代码在`/dist`文件夹中(Linux系统使用.tar.gz文件 and Windows使用.zip文件)。
+
+### 从Apache源代码发行版本构建
+- 什么是 `Apache源代码发行版本`?
+
+对于每个正式的Apache发行版本，都有一个完整且独立的源代码tar包，其中包含所有源代码。您可以从[SkyWalking Apache 下载页面](http://skywalking.apache.org/downloads/)下载它。 编译时不需要与git相关的东西。 只需按照以下步骤操作
+
+1. 准备JDK8和maven3
+1. 运行 `./mvnw clean package -DskipTests`
+1. 打包后的代码在`/dist`文件夹中(Linux系统使用.tar.gz文件 and Windows使用.zip文件)。
+
+## 设置IntelliJ IDEA
+1. 将项目按照maven项目的形式导入进来。
+1. 运行 `./mvnw compile -Dmaven.test.skip=true`编译项目并生成源代码。 因为Skywalking使用gRPC和protobuf。
+1. 所以还需要设置 **Generated Source Codes** 文件夹.
+ * **apm-protocol/apm-network/target/generated-sources/protobuf** 文件夹下的`grpc-java` 和 `java`
+ * **oap-server/server-core/target/generated-sources/protobuf** 文件夹下的`grpc-java` 和 `java`
+ * **oap-server/server-receiver-plugin/skywalking-istio-telemetry-receiver-plugin/target/generated-sources/protobuf** 文件夹下的`grpc-java` 和 `java`
+ * **oap-server/generate-tool/target/generated-sources** 文件夹下的 `antlr4`
+ * **oap-server/generated-analysis/target/generated-sources** 文件夹下的 `oal`
+
+## 设置Eclipse IDE
+1. 将项目按照maven项目的形式导入进来。
+2. 要支持多个源目录，需要添加以下配置 `incubator-skywalking/pom.xml`:
+
+```
+<plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>build-helper-maven-plugin</artifactId>
+ <version>1.8</version>
+ <executions>
+ <execution>
+ <id>add-source</id>
+ <phase>generate-sources</phase>
+ <goals>
+ <goal>add-source</goal>
+ </goals>
+ <configuration>
+ <sources>
+ <source>src/java/main</source>
+ <source>apm-protocol/apm-network/target/generated-sources/protobuf</source>
+ <source>apm-collector/apm-collector-remote/collector-remote-grpc-provider/target/generated-sources/protobuf</source>
+ </sources>
+ </configuration>
+ </execution>
+ </executions>
+</plugin>
+```
+3. 添加以下配置，让eclipse的M2e插件支持执行的解决方案配置
+
+```
+<pluginManagement>
+ <plugins>
+ <!--This plugin's configuration is used to store Eclipse m2e settings
+ only. It has no influence on the Maven build itself. -->
+ <plugin>
+ <groupId>org.eclipse.m2e</groupId>
+ <artifactId>lifecycle-mapping</artifactId>
+ <version>1.0.0</version>
+ <configuration>
+ <lifecycleMappingMetadata>
+ <pluginExecutions>
+ <pluginExecution>
+ <pluginExecutionFilter>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>build-helper-maven-plugin</artifactId>
+ <versionRange>[1.8,)</versionRange>
+ <goals>
+ <goal>add-source</goal>
+ </goals>
+ </pluginExecutionFilter>
+ </pluginExecution>
+ </pluginExecutions>
+ </lifecycleMappingMetadata>
+ </configuration>
+ </plugin>
+ </plugins>
+</pluginManagement>
+```
+4. 将Google guava依赖项添加到 **apm-collector-remote/collector-remote-grpc-provider/pom.xml**文件中
+
+```
+<dependency>
+ <groupId>com.google.guava</groupId>
+ <artifactId>guava</artifactId>
+ <version>24.0-jre</version>
+</dependency>
+```
+5. 运行 `./mvnw compile -Dmaven.test.skip=true`
+6. 运行 `maven update`. update命令前不能有clean(这将清除complie生成的proto转换Java文件)
+7. 运行 `./mvnw compile` 编译 collector-remote-grpc-provider 和 apm-protocol
+8. 刷新项目
diff --git a/docs/others/cn/guides/How-to-release.md b/docs/others/cn/guides/How-to-release.md
new file mode 100644
index 0000000..1f332d6
--- /dev/null
+++ b/docs/others/cn/guides/How-to-release.md
@@ -0,0 +1,377 @@
+Apache SkyWalking 发布指南
+--------------------
+本文档指导每个提交者在Apache Way中发布SkyWalking，并且还帮助提交者检查发布的投票。
+
+
+## 设置您的开发环境
+按照 [Apache maven部署环境文档](http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env)设置gpg工具和加密密码
+
+使用以下代码块作为模板并将其放入 ~/.m2/settings.xml
+
+```
+<settings>
+...
+ <servers>
+ <!-- To publish a snapshot of some part of Maven -->
+ <server>
+ <id>apache.snapshots.https</id>
+ <username> <!-- YOUR APACHE LDAP USERNAME --> </username>
+ <password> <!-- YOUR APACHE LDAP PASSWORD (encrypted) --> </password>
+ </server>
+ <!-- To stage a release of some part of Maven -->
+ <server>
+ <id>apache.releases.https</id>
+ <username> <!-- YOUR APACHE LDAP USERNAME --> </username>
+ <password> <!-- YOUR APACHE LDAP PASSWORD (encrypted) --> </password>
+ </server>
+ ...
+ </servers>
+</settings>
+```
+
+## 添加您的GPG公钥
+1. 将您的GPG公钥添加到 [SkyWalking GPG KEYS](https://dist.apache.org/repos/dist/release/incubator/skywalking/KEYS) 文件中,
+只有你是一个提交者，使用你的Apache id和密码登录这个svn，并更新文件。 **不要覆盖现有文件**
+1. 将您的GPG公钥上传到公共GPG站点。 如[MIT's 站点](http://pgp.mit.edu:11371/). 这个网站应该在Apache maven staging repository检查列表
+
+## 测试你的配置
+此步骤仅用于测试，如果您的env设置正确，则不需要每次都检查。
+```
+./mvnw clean install -Papache-release (这将构建工件，来源和标志)
+```
+
+## 准备发布
+```
+./mvnw release:clean
+./mvnw release:prepare -DautoVersionSubmodules=true -Pauto-submodule
+```
+_你可以在发布之前做一个GPG标志，如果你需要输入密码进行签名，而且maven没有给出机会，
+但只是失败。 运行`gpg --sign xxx`到任何文件都可以记住密码有足够的时间来发布._
+
+## 发布阶段
+```
+./mvnw release:perform -DskipTests -Pauto-submodule
+```
+1.将版本号设置为x.y.z，标记为** v ** x.y.z（版本标记必须以** v **开头，您将在下一步中找到目的。）
+1.该版本将自动插入临时存储库中。
+
+## 构建并签署源代码包
+```shell
+export RELEASE_VERSION=x.y.z (example: RELEASE_VERSION=5.0.0-alpha)
+cd tools/releasing
+sh create_source_release.sh
+```
+
+**注意**, `create_source_release.sh` 只适合MacOS。 欢迎任何人贡献Windows bat和Linux shell。
+
+这个脚本应该做以下事情
+1. 使用 `v` + `RELEASE_VERSION` 作为标记来克隆代码。
+1. 完成 `git submodule init/update` .
+1. 排除目标源tar中的所有不必要的文件，例如.git，.github，.gitmodules。 有关详细信息，请参阅脚本。
+1. 执行 `gpg` 和 `shasum 512`.
+
+
+应该在`tools/releasing`文件夹中找到`apache-skywalking-apm-incubating-x.y.z-src.tgz`和.asc, .sha512结尾的文件
+
+## 在Apache Nexus Staging存储库中查找和下载分发
+1. 使用ApacheId登录 `https://repository.apache.org/`。
+1. 跳转到 `https://repository.apache.org/#stagingRepositories`。
+1. 搜索 `skywalking` 并找到您的暂存存储库。
+1. 关闭存储库并等待所有检查通过。 在此步骤中，将检查您的GPG KEYS。参考[设置PGP文档](#add-your-gpg-public-key)，如果你以前没有这样做过。
+1. 跳转到 `{REPO_URL}/org/apache/skywalking/apache-skywalking-apm-incubating/x.y.z`
+1. 下载 `.tar.gz` 和 `.zip` 且有 .asc 和 .sha1 结尾的文件
+
+
+## 上传到Apache svn
+1. 使用ApacheId登录 `https://dist.apache.org/repos/dist/dev/incubator/skywalking/`。
+1. 创建文件夹，按发行版本和圆形命名，例如：x.y.z。
+1. 将源代码包上传到包含.asc，.sha512的文件夹
+ * 包名：apache-skywalking-incubating-x.y.z-src.tar.gz
+ * 有关详细信息，请参见“构建和签署源代码包”一节
+1. 使用.asc，.sha512将分发包上载到该文件夹
+ * 包名：apache-skywalking-incubating-x.y.z.tar.gz, apache-skywalking-incubating-x.y.z.zip
+ * 有关详细信息，请参见“在Apache Nexus Staging存储库中查找和下载分发”一节
+ * 创建.sha512包: `shasum -a 512 file > file.sha512`
+
+## 发表内部公告
+在开发邮件列表中发送公告邮件。
+
+```
+邮件标题: [ANNOUNCE] SkyWalking x.y.z test build available
+
+邮件内容:
+The test build of x.y.z is available.
+
+This is our Apache Incubator release.
+We welcome any comments you may have, and will take all feedback into
+account if a quality vote is called for this build.
+
+Release notes:
+
+ * https://github.com/apache/incubator-skywalking/blob/master/CHANGES.md
+
+Release Candidate:
+
+ * https://dist.apache.org/repos/dist/dev/incubator/skywalking/xxxx
+ * sha512 checksums
+ - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x-src.tgz
+ - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x.tar.gz
+ - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x.zip
+
+Maven 2 staging repository:
+
+ * https://repository.apache.org/content/repositories/xxxx/org/apache/skywalking/
+
+Release Tag :
+
+ * (Git Tag) x.y.z
+
+Release CommitID :
+
+ * https://github.com/apache/incubator-skywalking/tree/(Git Commit ID)
+ * Git submodule
+ * skywalking-ui: https://github.com/apache/incubator-skywalking-ui/tree/(Git Commit ID)
+ * apm-protocol/apm-network/src/main/proto: https://github.com/apache/incubator-skywalking-data-collect-protocol/tree/(Git Commit ID)
+ * oap-server/server-query-plugin/query-graphql-plugin/src/main/resources/query-protocol https://github.com/apache/incubator-skywalking-query-protocol/tree/(Git Commit ID)
+
+Keys to verify the Release Candidate :
+
+ * http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x2EF5026E70A55777 corresponding to pengys@apache.org
+
+Guide to build the release from source :
+
+ * https://github.com/apache/incubator-skywalking/blob/x.y.z/docs/en/guides/How-to-build.md
+
+A vote regarding the quality of this test build will be initiated
+within the next couple of days.
+```
+
+## 等待至少48小时的测试响应
+任何PPMC，提交者或贡献者都可以测试发布和反馈的功能。
+基于此，PPMC将决定是否开始投票。
+
+## 在dev群组中投票
+在`dev @ skywalking.apache.org`中投票
+
+```
+邮件标题: [VOTE] Release Apache SkyWalking (incubating) version x.y.z
+
+邮件内容:
+Hi All,
+This is a call for vote to release Apache SkyWalking (Incubating) version x.y.z.
+
+Release notes:
+
+ * https://github.com/apache/incubator-skywalking/blob/x.y.z/CHANGES.md
+
+Release Candidate:
+
+ * https://dist.apache.org/repos/dist/dev/incubator/skywalking/xxxx
+ * sha512 checksums
+ - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x-src.tgz
+ - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x.tar.gz
+ - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x.zip
+
+Maven 2 staging repository:
+
+ * https://repository.apache.org/content/repositories/xxxx/org/apache/skywalking/
+
+Release Tag :
+
+ * (Git Tag) x.y.z
+
+Release CommitID :
+
+ * https://github.com/apache/incubator-skywalking/tree/(Git Commit ID)
+ * Git submodule
+ * skywalking-ui: https://github.com/apache/incubator-skywalking-ui/tree/(Git Commit ID)
+ * apm-protocol/apm-network/src/main/proto: https://github.com/apache/incubator-skywalking-data-collect-protocol/tree/(Git Commit ID)
+ * oap-server/server-query-plugin/query-graphql-plugin/src/main/resources/query-protocol https://github.com/apache/incubator-skywalking-query-protocol/tree/(Git Commit ID)
+
+Keys to verify the Release Candidate :
+
+ * http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x2EF5026E70A55777 corresponding to pengys@apache.org
+
+Guide to build the release from source :
+
+ * https://github.com/apache/incubator-skywalking/blob/x.y.z/docs/en/guides/How-to-build.md
+
+Voting will start now (xxxx date) and will remain open for at least 72 hours, Request all PPMC members to give their vote.
+[ ] +1 Release this package.
+[ ] +0 No opinion.
+[ ] -1 Do not release this package because....
+```
+
+## 投票检查
+所有PPMC成员和提交者都应在投票+1之前检查这些。
+
+1. 功能测试。
+1. staging repository中的所有工件都使用.asc，.md5，* sha1文件发布
+1. 源代码和下发包 (apache-skywalking-incubating-x.y.z-src.tar.gz, apache-skywalking-incubating-x.y.z.tar.gz, apache-skywalking-incubating-x.y.z.zip)
+都应该在 `https://dist.apache.org/repos/dist/dev/incubator/skywalking/x.y.z` 且包含 .asc, .sha512
+1. `LICENSE` 和 `NOTICE` 文件在源代码和分发包中。
+1. 检查 `shasum -c apache-skywalking-apm-incubating-x.y.z-src.tgz.sha512`
+1. 构建发布源代码包 (apache-skywalking-incubating-x.y.z-src.tar.gz) by following this [文档](https://github.com/apache/incubator-skywalking/blob/master/docs/en/How-to-build.md#build-from-apache-source-codes).
+1. Apache RAT检查。运行`./mvnw apache-rat:check`. (源代码中没有二进制文件)
+1. 需要有免责声明
+
+投票结果应遵循这些。
+1.PPMC投票是+1绑定，所有其他投票是+1没有约束力。
+1.在72小时内，你得到至少3（+1绑定），并且+1比-1更多。投票通过。
+
+## 要求在Apache IPMC中投票
+在`general @ incubator.apache.org`中投票
+
+```
+邮件标题: [VOTE] Release Apache SkyWalking (incubating) version x.y.z
+
+邮件内容:
+Hi All,
+This is a call for vote to release Apache SkyWalking (Incubating) version x.y.z.
+
+The Apache SkyWalking community has tested, voted and approved the proposed
+release of Apache SkyWalking (Incubating) x.y.z
+
+We now kindly request the Incubator PMC members review and vote on this
+incubator release.
+
+SkyWalking: APM (application performance monitor) tool for distributed systems,
+especially designed for microservices, cloud native and container-based (Docker, Kubernetes, Mesos) architectures.
+Underlying technology is a distributed tracing system.
+
+Vote Thread:
+
+ * From `list.apache.org`
+
+Result Thread:
+
+ * From the vote thread.
+
+Release notes:
+
+ * https://github.com/apache/incubator-skywalking/blob/x.y.z/CHANGES.md
+
+Release Candidate:
+
+ * https://dist.apache.org/repos/dist/dev/incubator/skywalking/xxxx
+ * sha512 checksums
+ - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x-src.tgz
+ - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x.tar.gz
+ - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x.zip
+
+Maven 2 staging repository:
+
+ * https://repository.apache.org/content/repositories/xxxx/org/apache/skywalking/
+
+Release Tag :
+
+ * (Git Tag) x.y.z
+
+Release CommitID :
+
+ * https://github.com/apache/incubator-skywalking/tree/(Git Commit ID)
+ * Git submodule
+ * skywalking-ui: https://github.com/apache/incubator-skywalking-ui/tree/(Git Commit ID)
+ * apm-protocol/apm-network/src/main/proto: https://github.com/apache/incubator-skywalking-data-collect-protocol/tree/(Git Commit ID)
+ * oap-server/server-query-plugin/query-graphql-plugin/src/main/resources/query-protocol https://github.com/apache/incubator-skywalking-query-protocol/tree/(Git Commit ID)
+
+Keys to verify the Release Candidate :
+
+ * http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x2EF5026E70A55777 corresponding to pengys@apache.org
+
+Guide to build the release from source :
+
+ * https://github.com/apache/incubator-skywalking/blob/x.y.z/docs/en/guides/How-to-build.md
+
+Voting will start now (xxxx date) and will remain open for at least 72 hours, Request IPMC to give their vote.
+[ ] +1 Release this package.
+[ ] +0 No opinion.
+[ ] -1 Do not release this package because....
+```
+
+## 投票结果邮件
+关闭投票，如果：
+1. I在72小时内，你得到至少3（+1绑定），并且+1比-1更多。 投票通过。 在IPMC投票中，只有孵化器项目PMC
+投票将被视为+1绑定。
+1. 一些评论者在这个版本中发现了一些严重的错误，团队可以决定取消投票并准备一个新的RC。
+
+发送邮件到 `general@incubator.apache.org` 涉及投票结果和状态.
+```
+邮件标题: [Result][VOTE] Release Apache SkyWalking (incubating) version x.y.z
+
+邮件内容:
+Hi all,
+
+The vote for releasing Apache SkyWalking x.y.z (incubating) is closed, now.
+
+Vote result:
+x (+1 binding) (Names of voters)
+y -1.
+
+Thank you everyone for taking the time to review the release and help us.
+
+I will process to publish the release and send ANNOUNCE.
+```
+
+## 发版
+1. 将源代码tar球和发行版移动到 `https://dist.apache.org/repos/dist/release/incubator/skywalking/`.
+
+```
+> export SVN_EDITOR=vim
+> svn mv https://dist.apache.org/repos/dist/dev/incubator/skywalking/x.y.z https://dist.apache.org/repos/dist/release/incubator/skywalking
+....
+enter your apache password
+....
+
+```
+2. 在nexus staging repo中发布.
+3. 公共下载源和下发 tar/zip 位于 `http://www.apache.org/dyn/closer.cgi/incubator/skywalking/x.y.z/xxx`.
+我们只发布Apache镜像路径作为发布信息。
+4. 公共asc和sha512位于 `https://www.apache.org/dist/incubator/skywalking/x.y.z/xxx`
+5. 公共密钥指向 `https://www.apache.org/dist/incubator/skywalking/KEYS`
+6. 将ANNOUNCE邮件发送到 `general@incubator.apache.org` 和 `dev@skywalking.apache.org`.
+
+```
+邮件标题: [ANNOUNCE] Release Apache SkyWalking (incubating) version x.y.z
+
+邮件内容:
+Hi all,
+
+Apache SkyWalking (incubating) Team is glad to announce the first release of Apache SkyWalking Incubating x.y.z.
+
+SkyWalking: APM (application performance monitor) tool for distributed systems,
+especially designed for microservices, cloud native and container-based (Docker, Kubernetes, Mesos) architectures.
+Underlying technology is a distributed tracing system.
+
+Vote Thread:
+
+Download Links : http://skywalking.apache.org/downloads/
+
+Release Notes : https://github.com/apache/incubator-skywalking/blob/x.y.z/CHANGES.md
+
+Website: http://skywalking.apache.org/
+
+SkyWalking Resources:
+- Issue: https://github.com/apache/incubator-skywalking/issues
+- Mailing list: dev@skywalkiing.incubator.apache.org
+- Documents: https://github.com/apache/incubator-skywalking/blob/x.y.z/docs/README.md
+
+
+- Apache SkyWalking (incubating) Team
+
+=====
+*Disclaimer*
+
+Apache SkyWalking (incubating) is an effort undergoing incubation at The
+Apache Software Foundation (ASF), sponsored by the name of Apache
+Incubator PMC. Incubation is required of all newly accepted
+projects until a further review indicates that the
+infrastructure, communications, and decision making process have
+stabilized in a manner consistent with other successful ASF
+projects. While incubation status is not necessarily a reflection
+of the completeness or stability of the code, it does indicate
+that the project has yet to be fully endorsed by the ASF.
+```
+
+7. 更新网站下载页面。 http://skywalking.apache.org/downloads/ 。 包括新的下载源，分发，sha512，asc和文档，链接。 可通过遵循上述规则（3） - （6）找到链接。
+8. 在网站主页甚至页面上添加发布活动。 通过更改日志或主要功能宣布公开发布。
diff --git a/docs/others/cn/guides/Java-Plugin-Development-Guide.md b/docs/others/cn/guides/Java-Plugin-Development-Guide.md
new file mode 100644
index 0000000..615e13a
--- /dev/null
+++ b/docs/others/cn/guides/Java-Plugin-Development-Guide.md
@@ -0,0 +1,299 @@
+# 插件开发指南
+本文档描述了如何理解，开发和贡献插件。
+
+## 概念
+### Span
+Span是分布式跟踪系统中一个重要且通用的概念。
+可从[Google Dapper Paper](https://research.google.com/pubs/pub36356.html) 和
+[OpenTracing](http://opentracing.io)学习**Span**相关知识
+
+SkyWalking从2017年开始支持OpenTracing和OpenTracing-Java API，我们的Span概念与论文和OpenTracing类似。我们也扩展了Span。
+
+Span有三种类型
+
+1.1 EntrySpan
+EntrySpan代表服务提供者，也是服务器端的端点。 作为一个APM系统，我们的目标是
+应用服务器。 所以几乎所有的服务和MQ-comsumer都是EntrySpan。
+
+1.2 LocalSpan
+LocalSpan表示普通的Java方法，它与远程服务无关，也不是MQ生产者/消费者
+也不是服务（例如HTTP服务）提供者/消费者。
+
+1.3 ExitSpan
+ExitSpan代表一个服务客户端或MQ的生产者，在SkyWalking的早期命名为“LeafSpan”。
+例如 通过JDBC访问DB，读取Redis / Memcached被编目为ExitSpan。
+
+### ContextCarrier
+为了实现分布式跟踪，需要绑定跨进程的跟踪，并且应该传播上下文
+整个过程。 这就是ContextCarrier的职责。
+
+以下是有关如何在`A -> B`分布式调用中使用**ContextCarrier**的步骤。
+
+1. 在客户端，创建一个新的空的`ContextCarrier`。
+1. 通过 `ContextManager#createExitSpan` 创建一个 ExitSpan 或者 使用 `ContextManager#inject` 来初始化 `ContextCarrier`.
+1. 将`ContextCarrier`所有信息放到heads(例如HTTP HEAD)、attachments(例如Dubbo RPC framework) 或者messages(例如Kafka)
+1. 通过服务调用，将`ContextCarrier`传递到服务端。
+1. 在服务端，在对应组件的heads、attachments或messages获取`ContextCarrier`所有消息。
+1. `ContestManager#createEntrySpan`创建EntrySpan 或者使用 `ContextManager#extract` 将服务端和客户端的绑定。
+
+让我们通过Apache HTTPComponent client插件 和Tomcat 7服务器插件演示，步骤如下:
+
+1. 客户端Apache HTTPComponent client插件
+
+```java
+ span = ContextManager.createExitSpan("/span/operation/name", contextCarrier, "ip:port");
+ CarrierItem next = contextCarrier.items();
+ while (next.hasNext()) {
+ next = next.next();
+ httpRequest.setHeader(next.getHeadKey(), next.getHeadValue());
+ }
+```
+
+2. 服务端Tomcat 7服务器插件
+
+```java
+ ContextCarrier contextCarrier = new ContextCarrier();
+ CarrierItem next = contextCarrier.items();
+ while (next.hasNext()) {
+ next = next.next();
+ next.setHeadValue(request.getHeader(next.getHeadKey()));
+ }
+
+ span = ContextManager.createEntrySpan(“/span/operation/name”, contextCarrier);
+```
+
+### ContextSnapshot
+除了跨进程，跨线程也是需要支持的，例如异步线程（内存中的消息队列）和批处理在java中很常见，跨进程和跨线程十分相似，因为都是需要传播
+上下文。 唯一的区别是，不需要跨线程序列化。
+
+以下是有关跨线程传播的三个步骤：
+1. 使用`ContextManager＃capture`获取ContextSnapshot对象。
+2. 让子线程以任何方式，通过方法参数或由现有参数携带来访问ContextSnapshot
+3. 在子线程中使用`ContextManager#continies`。
+
+## 核心 API
+### ContextManager
+ContextManager提供所有主要API。
+
+1. Create EntrySpan
+
+```java
+public static AbstractSpan createEntrySpan(String endpointName, ContextCarrier carrier)
+```
+按操作名称创建 EntrySpan (例如服务名称, uri) 和 **ContextCarrier**.
+
+2. Create LocalSpan
+
+```java
+public static AbstractSpan createLocalSpan(String endpointName)
+```
+按操作名称创建 LocalSpan (例如完整的方法结构)
+
+3. Create ExitSpan
+
+```java
+public static AbstractSpan createExitSpan(String endpointName, ContextCarrier carrier, String remotePeer)
+```
+按操作名称创建 ExitSpan (例如服务名称, uri) 和 **ContextCarrier** 和 对端地址 (例如ip+port或hostname+port)
+
+### AbstractSpan
+```java
+ /**
+ * Set the component id, which defines in {@link ComponentsDefine}
+ *
+ * @param component
+ * @return the span for chaining.
+ */
+ AbstractSpan setComponent(Component component);
+
+ /**
+ * Only use this method in explicit instrumentation, like opentracing-skywalking-bridge.
+ * It it higher recommend don't use this for performance consideration.
+ *
+ * @param componentName
+ * @return the span for chaining.
+ */
+ AbstractSpan setComponent(String componentName);
+
+ AbstractSpan setLayer(SpanLayer layer);
+
+ /**
+ * Set a key:value tag on the Span.
+ *
+ * @return this Span instance, for chaining
+ */
+ AbstractSpan tag(String key, String value);
+
+ /**
+ * Record an exception event of the current walltime timestamp.
+ *
+ * @param t any subclass of {@link Throwable}, which occurs in this span.
+ * @return the Span, for chaining
+ */
+ AbstractSpan log(Throwable t);
+
+ AbstractSpan errorOccurred();
+
+ /**
+ * Record an event at a specific timestamp.
+ *
+ * @param timestamp The explicit timestamp for the log record.
+ * @param event the events
+ * @return the Span, for chaining
+ */
+ AbstractSpan log(long timestamp, Map<String, ?> event);
+
+ /**
+ * Sets the string name for the logical operation this span represents.
+ *
+ * @return this Span instance, for chaining
+ */
+ AbstractSpan setOperationName(String endpointName);
+```
+除了设置操作名称，标签信息和日志外，还要设置两个属性，即component（组件）和layer（层），特别是对于EntrySpan和ExitSpan。
+
+SpanLayer 是span的编目. 有五个值:
+1. UNKNOWN (默认)
+1. DB
+1. RPC_FRAMEWORK, （为了RPC框架，非普通的HTTP调用）for a RPC framework, not an ordinary HTTP
+1. HTTP
+1. MQ
+
+组件ID由SkyWalking项目定义和保留，对于组件的名称或ID的扩展，请遵循[组件库的定义与扩展](Component-library-settings.md)
+
+## 开发插件
+### Abstract（抽象）
+跟踪的基本方法是拦截Java方法，使用字节码操作技术和AOP概念。
+SkyWalking包装了字节码操作技术并跟踪上下文的传播，
+所以你只需要定义拦截点（换句话说就是Spring的切面）
+
+### Intercept（拦截）
+SkyWalking提供两类通用的定义去拦截构造器，实例方法和类方法。
+* Extend `ClassInstanceMethodsEnhancePluginDefine` defines `Contructor` intercept points and `instance method` intercept points.
+* 继承 `ClassInstanceMethodsEnhancePluginDefine` 定义 `Contructor`（构造器）拦截点和 `instance method`（实例化方法）拦截点.
+* 继承 `ClassStaticMethodsEnhancePluginDefine` 定义 `class method`（类方法）拦截点.
+
+当然，您也可以集成`ClassEnhancePluginDefine`去设置所有的拦截点，担着不常用。
+
+### Implement plugin（实现插件）
+下文，我将通过扩展`ClassInstanceMethodsEnhancePluginDefine`来演示如何实现一个插件
+
+1. 定义目标类的名称
+
+```java
+protected abstract ClassMatch enhanceClass();
+```
+
+ClassMatch 以下有四种方法表示如何去匹配目标类:
+* byName, 通过完整的类名(package name + `.` + class name)（包名+类名）。
+* byClassAnnotationMatch, 通过目标类存在某些注释。
+* byMethodAnnotationMatch, 通过目标类的方法存在某些注释.
+* byHierarchyMatch, 通过目标类的父类或接口
+
+**注意事项**:
+* 禁止使用 `*.class.getName()` 去获取类名， 建议你使用文字字符串，这是为了
+避免ClassLoader问题。
+* `by*AnnotationMatch` 不支持继承的注释.
+* 非必要的话，不推荐使用 `byHierarchyMatch`, 因为使用它可能会触发拦截
+许多未被发现的方法，会导致性能问题和不稳定。
+
+实例：
+
+```java
+@Override
+protected ClassMatch enhanceClassName() {
+ return byName("org.apache.catalina.core.StandardEngineValve");
+}
+
+```
+
+2. 定义实例方法拦截点
+
+```java
+protected InstanceMethodsInterceptPoint[] getInstanceMethodsInterceptPoints();
+
+public interface InstanceMethodsInterceptPoint {
+ /**
+ * class instance methods matcher.
+ *
+ * @return methods matcher
+ */
+ ElementMatcher<MethodDescription> getMethodsMatcher();
+
+ /**
+ * @return represents a class name, the class instance must instanceof InstanceMethodsAroundInterceptor.
+ */
+ String getMethodsInterceptor();
+
+ boolean isOverrideArgs();
+}
+```
+
+也可以使用`Matcher`来设置目标方法。 如果要更改参数，请在`isOverrideArgs`中返回** true ** 参考拦截器。
+
+以下部分将告诉您如何实现拦截器。
+
+3. Add plugin define into skywalking-plugin.def file
+```properties
+tomcat-7.x/8.x=TomcatInstrumentation
+```
+
+
+### 实现一个拦截器
+作为一个实例方法的拦截器，需要实现
+`org.apache.skywalking.apm.agent.core.plugin.interceptor.enhance.InstanceMethodsAroundInterceptor`
+```java
+/**
+ * A interceptor, which intercept method's invocation. The target methods will be defined in {@link
+ * ClassEnhancePluginDefine}'s subclass, most likely in {@link ClassInstanceMethodsEnhancePluginDefine}
+ *
+ * @author wusheng
+ */
+public interface InstanceMethodsAroundInterceptor {
+ /**
+ * called before target method invocation.
+ *
+ * @param result change this result, if you want to truncate the method.
+ * @throws Throwable
+ */
+ void beforeMethod(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes,
+ MethodInterceptResult result) throws Throwable;
+
+ /**
+ * called after target method invocation. Even method's invocation triggers an exception.
+ *
+ * @param ret the method's original return value.
+ * @return the method's actual return value.
+ * @throws Throwable
+ */
+ Object afterMethod(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes,
+ Object ret) throws Throwable;
+
+ /**
+ * called when occur exception.
+ *
+ * @param t the exception occur.
+ */
+ void handleMethodException(EnhancedInstance objInst, Method method, Object[] allArguments, Class<?>[] argumentsTypes,
+ Throwable t);
+}
+```
+在before，after和exception处理阶段使用核心API。
+
+
+### 将插件贡献到Apache SkyWalking 仓库中
+我们欢迎大家贡献插件。
+
+请按照以下步骤操作：
+
+1. 提交有关您要贡献哪些插件的问题，包括支持的版本。
+1. 在`apm-sniffer / apm-sdk-plugin`或`apm-sniffer / optional-plugins`下创建子模块，名称应包含支持的库名和版本
+1. Create sub modules under `apm-sniffer/apm-sdk-plugin` or `apm-sniffer/optional-plugins`, and the name should include supported library name and versions
+1. 按照本指南进行开发。 确保提供评论和测试用例。
+1. 开发并测试。
+1. 发送拉取请求并要求审核。
+1. 提供自动测试用例。
+所有测试用例都托管在[SkywalkingTest/skywalking-agent-testcases repository](https://github.com/SkywalkingTest/skywalking-agent-testcases).
+关于如何编写测试用例，请按照[如何编写](https://github.com/SkywalkingTest/skywalking-agent-testcases/blob/master/docs/how-to-write-a-plugin-testcase.md) 文档来实现.
+1. 在提供自动测试用例并在CI中递交测试后，插件提交者会批准您的插件。
+1. SkyWalking接受的插件。
diff --git a/docs/others/cn/guides/README.md b/docs/others/cn/guides/README.md
index a05f9ea..390e3db 100644
--- a/docs/others/cn/guides/README.md
+++ b/docs/others/cn/guides/README.md
@@ -1,2 +1,43 @@
-# 指南
-TODO
+# 贡献指南
+你可以通过以下方式，为SkyWalking社区做成贡献。
+
+- 审阅SkyWalking的文档，指出或修复文档不准确的地方，也可以将SkyWalking文档翻译成其他语言。
+- 下载我们的[发布版本](http://skywalking.apache.org/downloads/)，尝试用其监控你的应用程序，并向我们反馈您的想法、疑问或使用案例。
+- 阅读我们的源码，带着细节信息向我们提问。
+- 发现bug时，可在这里[提交问题](https://github.com/apache/incubator-skywalking/issues), 并且您也可以尝试修复它。
+- 你可以从完成[社区需要的帮助](https://github.com/apache/incubator-skywalking/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)，
+着手做起.
+- 提交问题或讨论在[GitHub问题处](https://github.com/apache/incubator-skywalking/issues/new).
+- 通过[网页邮件列表](https://lists.apache.org/list.html?dev@skywalking.apache.org)查看所有邮件的讨论，如果您是SkyWalking项目的committer，可在浏览器模式下登录并使用邮件列表。否则，根据按照下面进行订阅。
+- 问题的报告和讨论也可在 `dev@skywalking.apache.org`进行，
+发送邮件到`dev-subscribe@skywalking.apache.org`，按照回复订阅邮件列表。
+
+
+## 与我们联系
+以下所有渠道均向社区开放，您可以选择自己喜欢的方式。
+
+* 提交[问题](https://github.com/apache/incubator-skywalking/issues)
+* 邮件列表: **dev@skywalking.apache.org**. 发送邮件到 `dev-subscribe@skywalking.apache.org`，按照回复订阅邮件列表。
+* [Gitter](https://gitter.im/openskywalking/Lobby)
+* QQ群: 392443393
+
+## 对于代码开发者
+作为开发者，首先阅读[编译指南](How-to-build.md). 它会告诉你如何在本地构建。
+
+### 项目扩展
+SkyWalking项目支持许多扩展现有功能的方法。 如果你对这些方式感兴趣，
+阅读以下指南。
+
+- [Java agent 插件开发指南](Java-Plugin-Development-Guide.md).
+本指南将帮助您开发SkyWalking Java agent插件以支持更多框架或组件。 无论是进行开源插件或私有插件的开发都需要阅读这个指南。
+- 如果您想开发其他语言的探针或组件，请阅读[组件库定义和扩展](Component-library-settings.md) 文档.
+- [数据存储扩展开发指南](storage-extention.md). 除了官方已经支持的存储实现外，可帮助钱在的贡献者实现新的数据存储的实现。
+- [通过oal脚本自定义分析](write-oal.md). 指导您使用oal脚本来提供自己所需的指标。
+### UI开发者
+Skywalking UI 由静态页面和Web容器构成。
+
+- **静态页面** 是建立在 [Ant Design Pro](https://pro.ant.design/)之上，Skywalking UI源码托管在[Skywalking UI](https://github.com/apache/incubator-skywalking-ui)。
+- **Web容器** 源代码在`apm-webapp`模块中。这是一个简单的zuul代理，用于托管静态资源并使用GraphQL想后端发送查询请求。
+
+## 发布
+[Apache发布指南](How-to-release.md)向提交者团队介绍了正式的Apache版本发布流程，以避免破坏任何Apache规则。如果您在重新分发中保留我们的许可和通知，则Apache许可允许每个人重新分发。
\ No newline at end of file
diff --git a/docs/others/cn/guides/backend-oal-scripts.md b/docs/others/cn/guides/backend-oal-scripts.md
new file mode 100644
index 0000000..cba020c
--- /dev/null
+++ b/docs/others/cn/guides/backend-oal-scripts.md
@@ -0,0 +1,11 @@
+# 官方 OAL(可观测性分析语言) 脚本
+首先请阅读[OAL 介绍](../../../en/concepts-and-designs/oal.md).
+
+发行版本中官方脚本:`generated-analysis-x.y.z.jar/official_analysis.oal`，并且源代码库在模块`server-core`中**src/main/resources/official_analysis.oal**。
+**注意**, 这个文件虽然包含在发行版本中，但是在项目运行期间不会起任何作用。您需要使用OAL工具器去真实的分析代码。所生成的代码在`server-core`模块**org.apache.skywalking.oap.server.core.analysis.generated**中
+
+此脚本中命名的所有度量标准都可用于警报和UI查询。 当然，你可以改变这个
+脚本并重新生成分析过程和度量标准，例如添加过滤条件。
+
+如果您尝试添加或删除某些指标，UI项目可能出现问题，我们建议您在计划时执行此操作是
+基于自定义分析核心构建自己的UI。
\ No newline at end of file
diff --git a/docs/others/cn/guides/storage-extention.md b/docs/others/cn/guides/storage-extention.md
new file mode 100644
index 0000000..0996b77
--- /dev/null
+++ b/docs/others/cn/guides/storage-extention.md
@@ -0,0 +1,41 @@
+# 数据存储扩展
+SkyWalking g已经提供了多种存储解决方案。在本文档中，您可以
+学习如何轻松实现新存储。
+
+## 定义您的数据存储提供实现
+1. 定义一个类扩展 `org.apache.skywalking.oap.server.library.module.ModuleProvider`.
+2. 将此数据存储提供实现继承存储模块。
+```java
+@Override
+public Class<? extends ModuleDefine> module() {
+ return StorageModule.class;
+}
+```
+
+## 实现所有DAO接口
+下面是所有数据存储所需实现的DAO接口
+
+1. IServiceInventoryCacheDAO
+1. IServiceInstanceInventoryCacheDAO
+1. H2EndpointInventoryCacheDAO
+1. H2NetworkAddressInventoryCacheDAO
+1. IBatchDAO
+1. StorageDAO
+1. IRegisterLockDAO
+1. H2TopologyQueryDAO
+1. IMetricQueryDAO
+1. ITraceQueryDAO
+1. IMetadataQueryDAO
+1. IAggregationQueryDAO
+1. IAlarmQueryDAO
+1. IHistoryDeleteDAO
+
+## 注册所有的service实现
+在 `public void prepare()`, 使用 `this#registerServiceImplementation` 方法去注册绑定您的接口实现。
+
+## 实例
+`org.apache.skywalking.oap.server.storage.plugin.elasticsearch.StorageModuleElasticsearchProvider`
+或 `org.apache.skywalking.oap.server.storage.plugin.jdbc.mysql.MySQLStorageProvider` 就是一个很好的例子。
+
+## 重新发布新的数据存储实现
+您不必为了实现数据存储而克隆主托管库，您可以轻松地依赖我们的Apache版本。看一下 [OpenSkywalking/SkyWalking-With-Es5x-Storage](https://github.com/OpenSkywalking/SkyWalking-With-Es5x-Storage) 仓库, SkyWalking v6 重新发布 ElasticSearch 5 TCP 链接数据存储的实现。
\ No newline at end of file
diff --git a/docs/others/cn/guides/write-oal.md b/docs/others/cn/guides/write-oal.md
new file mode 100644
index 0000000..e62d81a
--- /dev/null
+++ b/docs/others/cn/guides/write-oal.md
@@ -0,0 +1,15 @@
+# 编写 OAL(可观测性分析语言) 脚本
+阅读 [OAL 概述](../../../en/concepts-and-designs/oal.md) 以了解oal脚本。
+
+## 在源代码中查找oal脚本
+官方official_analysis.oal在[这里](../../../../oap-server/generated-analysis/src/main/resources/official_analysis.oal).
+
+## 生成工具
+`oap-server/generate-tool` 模块包含编译工具的源代码。 该工具已经集成在
+maven编译阶段。 所以，除非您想要更改工具源代码，否则无需进行任何设置。
+
+运行 `./mvnw compile` 或 `./mvnw package`, 生成的oal脚本代码位于`oap-server/generate-tool/target/generated-sources/oal/*`.
+
+## 编写并重新编译
+您可以更改`official_analysis.oal`脚本, 然后重新编译代码.
+生成的代码位于 **oap-server/generated-analysis/target/generated-sources/oal**.
\ No newline at end of file