Merge pull request #134 from francis-du/master

[DOCS] Improved documentation and updated a blog
Qihoo360 · Jan 6, 2020 · 2323829 · 2323829
2 parents 61c7a55 + f1c0f5c
commit 2323829
Show file tree

Hide file tree

Showing 26 changed files with 166 additions and 58 deletions.
diff --git a/docs/about/faq.md b/docs/about/faq.md
@@ -1 +1,3 @@
-[English](./faq.md)|[中文](../zh/about/faq.md)
+[English](./faq.md)|[中文](../zh/about/faq.md)
+
+# FAQ
diff --git a/docs/about/license.md b/docs/about/license.md
@@ -1,4 +1,4 @@
-## **MIT License**
+# **MIT License**
 
 **Copyright (c) 2018 <QSql Project>**
 

diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md
@@ -1,6 +1,6 @@
 [English](./release-notes.md)|[中文](../zh/about/release-notes.md)
 
-## **RELEASE-0.6**
+# **RELEASE-0.6**
 
 **0.6版涉及的改动如下：**
 
@@ -24,5 +24,5 @@
 
 - 支持混算模式下JDBC数据源的分布式查询。
 
-## **RELEASE-0.5**
+# **RELEASE-0.5**
 - 无
diff --git a/docs/blog/2019.md b/docs/blog/2019.md
@@ -1,7 +1,7 @@
-## 2019-08-27
+# 2019-08-27
 
 [360多数据源混合查询引擎的前世今生 | 刘思源](https://mp.weixin.qq.com/s/ZdWi5CtBE_38t-brGkyB3g)
 
-## 2019-01-09
+# 2019-01-09
 
 [Quicksql——更简单，更安全，更快速的跨数据源统一SQL查询引擎 | 360技术](https://mp.weixin.qq.com/s/XUFhq5iwK-Lfbf8vSXr7tA)
diff --git a/docs/blog/2020.md b/docs/blog/2020.md
@@ -0,0 +1,3 @@
+# 2020-01-03
+
+[Quick SQL在线文档主题色投票结果 | Francis](articles/在线文档主题色投票结果.md)
diff --git a/docs/blog/articles/在线文档主题色投票结果.md b/docs/blog/articles/在线文档主题色投票结果.md
@@ -0,0 +1,37 @@
+# Quick SQL在线文档主题色投票结果出来啦
+
+上周四，也就是2020年01月02日，我们发起了一个关于我们
+[在线文档的主题颜色投票](https://form.chinagdg.org/forms/d/e/1FAIpQLSc4CdXZsDZO3jat8rPgm9VEjXfrqlPQB5DCOva0OTcFemp16w/viewform)
+
+首先呢，通过本次投票，极大的鼓舞了 Quick SQL 社区的小伙伴儿的积极性
+(虽然只有20个人参与)，但是群里的小哥看到我们的新的文档
+表示一下充满了信心，要来贡献代码呢~-~
+
+其次，我们正在逐渐的国际化，最近也开了Slack Channel，我们日常的一些
+开发和讨论都在[Slack](https://quicksql.readthedocs.io/en/latest/community/channel/) 
+上，欢迎大家加入讨论和贡献[代码](https://quicksql.readthedocs.io/en/latest/community/contribution-code/)
+和[文档](https://quicksql.readthedocs.io/en/latest/community/contribution-docs/)哦~
+另外我们的翻译平台也在逐步的建立。总之就是我们会越来越好哒^-^
+
+拉好小板凳,现在让我来公布下投票结果~
+
+获得我们`页面整体色调`人数最多奖的是... `Blue(15%)`
+
+![primary](../../../images/primary-color-count.png)
+
+获得我们`鼠标经过时色调`人数最多奖的是... `Red(20%)`
+
+![accent](../../../images/accent-color-count.png)
+
+我们接下来会将我们的主题颜色改成以上的两位获奖色
+感谢大家的投票，希望下次投票人能多点,`手动捂脸.jpg`
+
+## 加入我们
+
+[![Slack](../../../images/slack.png)](https://join.slack.com/t/quicksql/shared_invite/enQtODkwMzM0Njc3NTExLWQxNjRlY2M5YTlkMTk4OTM2YzhjMjUxYTUyN2VlNzJlNzQwM2E4YjkxNzA4MDllODg5NWUxNDY4MTMyMzczMWI)
+[![Github](../../../images/github.png)](https://github.com/qihoo360/Quicksql/issues)
+[![QQ](../../../images/qq.png)](https://jq.qq.com/?_wv=1027&k=5782R6F)
+
+
+
+
diff --git a/docs/community/channel.md b/docs/community/channel.md
@@ -1,4 +1,4 @@
-## Join us
+# Join us
 
 [![Slack](../images/slack.png)](https://join.slack.com/t/quicksql/shared_invite/enQtODkwMzM0Njc3NTExLWQxNjRlY2M5YTlkMTk4OTM2YzhjMjUxYTUyN2VlNzJlNzQwM2E4YjkxNzA4MDllODg5NWUxNDY4MTMyMzczMWI)
 [![Github](../images/github.png)](https://github.com/qihoo360/Quicksql/issues)

diff --git a/docs/community/contribution-code.md b/docs/community/contribution-code.md
@@ -1,3 +1,30 @@
 [English](./contribution-code.md)|[中文](../zh/community/contribution-code.md)
 
-## Contributing code
+# Contributing Code
+
+We welcome contributions.
+
+If you are interested in Quicksql, you can download the source code from GitHub and execute the following maven command at the project root directory：
+
+```shell
+mvn -DskipTests clean package
+```
+
+If you are planning to make a large contribution, talk to us first! It helps to agree on the general approach. Log a Issures on GitHub for your proposed feature.
+
+Fork the GitHub repository, and create a branch for your feature.
+
+Develop your feature and test cases, and make sure that `mvn install` succeeds. (Run extra tests if your change warrants it.)
+
+Commit your change to your branch.
+
+If your change had multiple commits, use `git rebase -i master` to squash them into a single commit, and to bring your code up to date with the latest on the main line.
+
+Then push your commit(s) to GitHub, and create a pull request from your branch to the QSQL master branch. Update the JIRA case to reference your pull request, and a committer will review your changes.
+
+The pull request may need to be updated (after its submission) for two main reasons:
+
+1. you identified a problem after the submission of the pull request;
+2. the reviewer requested further changes;
+
+In order to update the pull request, you need to commit the changes in your branch and then push the commit(s) to GitHub. You are encouraged to use regular (non-rebased) commits on top of previously existing ones.
diff --git a/docs/community/contribution-docs.md b/docs/community/contribution-docs.md
@@ -1,6 +1,6 @@
 [English](./contribution-docs.md)|[中文](../zh/community/contribution-docs.md)
 
-## Contributing documents
+# Contributing documents
 
 ## Installing Python
 Install [Python](https://www.python.org/) or [Anaconda](https://www.anaconda.com/).

diff --git a/docs/community/contributors.md b/docs/community/contributors.md
@@ -1,3 +1,5 @@
+# Contributors
+
 Sort alphabetically,Show only GitHub ID without avatar.
 
 ### Without avatar

diff --git a/docs/deployment/deployment.md b/docs/deployment/deployment.md
@@ -1,11 +1,11 @@
-[English](../../deployment/deployment.md)|[中文](./deployment.md)
+[English](./deployment.md)|[中文](../zh/deployment/deployment.md)
 
 
-## 部署指南
+# 部署指南
 
 (引言)本页面将提供Quicksql支持的数据源和引擎的配套版本和依赖包调整方式，此外，元数据的管理方式也将被提及。
 
-### 数据源管理
+## 数据源管理
 
 Quicksql提供默认的数据源客户端版本，以下是版本关系表，用户可以自行替换Jar包更替。
 
@@ -29,7 +29,7 @@ $ cp mysql-connector-java-8.0.18.jar ./
 $ ../bin/quicksql -e "SELECT * FROM TABLE_IN_MySQL8"
 ``````
 
-### 计算引擎管理
+## 计算引擎管理
 
 Quicksql使用的计算引擎可以由用户自定义参数，参数可以在./conf/qsql-runner.properties中修改：
 
@@ -52,11 +52,11 @@ Quicksql使用的计算引擎可以由用户自定义参数，参数可以在./c
 | ------------- | ------- | ------- |
 | 待补充        | 待补充  | 待补充  |
 
-### 元数据管理
+## 元数据管理
 
 Quicksql使用一个独立的存储来存放各类数据源的元数据及配置信息，默认的元数据存储为Sqlite，一个文档数据库，在普通开发环境下可以使用。如果对并发能力有更高的要求，可以更换元数据存储为MySQL等，采用通用的JDBC标准，可参考以下配置：
 
-#### 元数据参数
+### 元数据参数
 
 | Property Name               | Default                | Meaning                                                      |
 | --------------------------- | ---------------------- | ------------------------------------------------------------ |

diff --git a/docs/images/accent-color-count.png b/docs/images/accent-color-count.png
diff --git a/docs/images/primary-color-count.png b/docs/images/primary-color-count.png
diff --git a/docs/reference/develop.md b/docs/reference/develop.md
@@ -1,5 +1,6 @@
-[English](../../reference/develop.md)|[中文](./develop.md)
-## QuickSQL开发
+[English](./develop.md)|[中文](../zh/reference/develop.md)
+
+# QuickSQL开发
 
 (1)  第一步找到QuickSQL项目 https://github.com/Qihoo360/Quicksql 
 

diff --git a/docs/reference/getting-started.md b/docs/reference/getting-started.md
@@ -1,9 +1,10 @@
 [English](./getting-started.md)|[中文](../zh/reference/getting-started.md)
-### Tutorials
+
+# Tutorials
 
 包含启动项目和运行范例的流程引导
 
-#### Setup on Linux\MacOS
+## Setup on Linux\MacOS
 
 在Linux\MacOS上 运行Quicksql非常简单，但需要确保环境预置完整，依赖的环境有：
 
@@ -22,7 +23,7 @@ $ cd quicksql-realease-0.7.0
 $ vim ./conf/quicksql-env.sh #Set Your Basic Environment.
 ``````
 
-##### 运行样例查询
+## 运行样例查询
 
 进入bin目录，执行quicksql-example脚本。（这里使用了内嵌Elasticsearch Server与Csv数据源作一个关联过滤）
 
@@ -42,7 +43,7 @@ $ ./bin/quicksql-example com.qihoo.qsql.CsvJoinWithEsExample #换成选项型，
 +------+-------+----------+--------+------+-------+------+
 ```
 
-##### 运行真实查询
+## 运行真实查询
 
 在Quicksql上运行查询前需要将连接信息以及表、字段信息采集入库。
 
@@ -158,7 +159,7 @@ $ ./meta-extract -p "{\"esNodes\": \"192.168.1.1\",\"esPort\": \"9090\",\"esUser
 
 注意：Shell中双引号是特殊字符，传JSON参数时需要做转义！！
 
-##### 第二页 从命令行提交查询
+### 从命令行提交查询
 
 从命令行查询是Quicksql提供的最基本的查询方式之一。
 
@@ -210,11 +211,11 @@ $ ./bin/quicksql.sh -e  "INSERT INTO \`hdfs://cluster:9000/hello/world\` IN HDFS
 
 	(2) 在非分布式执行中，即使设置了master、worker_memory等参数也不会生效；
 
-##### 第三页 从应用提交查询
+### 从应用提交查询
 
 Quicksql支持使用Client/Server模式的JDBC连接进行查询，用户的应用可以通过引入Driver包与Server建立连接进行联邦查询。
 
-#### Server端
+## Server端
 
 **启动Server**
 
@@ -230,7 +231,7 @@ $ ./bin/quicksql-server.sh start -P 5888 -R spark -M yarn-client
 
 -M：指定spark任务资源调度方式，yarn-client或yarn-cluster等，默认为local[1]
 
-#### Client端
+## Client端
 
 **应用接入**
 

diff --git a/docs/reference/sql-language.md b/docs/reference/sql-language.md
@@ -1,5 +1,8 @@
 [English](./sql-language.md)|[中文](../zh/reference/sql-language.md)
-#### SQL grammar
+
+# SQL grammar
+
+## SQL grammar
 
 ```sql
 select:
@@ -61,7 +64,7 @@ describe:
 
 ```
 
-#### Functions and Operators
+## Functions and Operators
 
 ```sql
 Conditional Expressions
@@ -146,7 +149,7 @@ COUNT(*|1|...) | SUM([ALL | DISTINCT]numeric) | AVG([ALL | DISTINCT]numeric)
 
 ```
 
-#### Key words
+## Key words
 
 ```sql
 support:
@@ -178,7 +181,7 @@ VALUE | VALUES | VALUE_OF | VAR_POP | VAR_SAMP | VARBINARY | VARCHAR | VARYING |
 WEEK | WHEN | WHENEVER | WHERE | WIDTH_BUCKET | WINDOW | WITH | WITHIN | WITHOUT | WORK | WRAPPER | WRITE | XML | YEAR | ZONE
 ```
 
-#### Data Types
+## Data Types
 
 ```
 lsupport:

diff --git a/docs/zh/about/faq.md b/docs/zh/about/faq.md
@@ -1 +1,3 @@
-[English](../../about/faq.md)|[中文](./faq.md)
+[English](../../about/faq.md)|[中文](./faq.md)
+
+# FAQ
diff --git a/docs/zh/about/license.md b/docs/zh/about/license.md
@@ -1,4 +1,4 @@
-## **MIT License**
+# **MIT License**
 
 **Copyright (c) 2018 <QSql Project>**
 

diff --git a/docs/zh/about/release-notes.md b/docs/zh/about/release-notes.md
@@ -1,6 +1,6 @@
 [English](../../about/release-notes.md)|[中文](./release-notes.md)
 
-## **RELEASE-0.6**
+# **RELEASE-0.6**
 
 **0.6版涉及的改动如下：**
 
@@ -24,5 +24,5 @@
 
 - 支持混算模式下JDBC数据源的分布式查询。
 
-## **RELEASE-0.5**
+# **RELEASE-0.5**
 - 无
diff --git a/docs/zh/community/channel.md b/docs/zh/community/channel.md
@@ -1,4 +1,4 @@
-## Join us
+# Join us
 
 [![Slack](../../images/slack.png)](https://join.slack.com/t/quicksql/shared_invite/enQtODkwMzM0Njc3NTExLWQxNjRlY2M5YTlkMTk4OTM2YzhjMjUxYTUyN2VlNzJlNzQwM2E4YjkxNzA4MDllODg5NWUxNDY4MTMyMzczMWI)
 [![Github](../../images/github.png)](https://github.com/qihoo360/Quicksql/issues)

diff --git a/docs/zh/community/contribution-code.md b/docs/zh/community/contribution-code.md
@@ -1,3 +1,29 @@
 [English](../../community/contribution-code.md)|[中文](./contribution-code.md)
 
-# Contribution
+# 贡献代码
+
+我们非常欢迎贡献代码。
+
+如果需要提交的代码比较多，可以先和我们谈谈！记录一条[Issues]。这对双方达成共识是有帮助的。
+
+Fork QSQL GitHub库，并为您的提交创建一个分支。
+
+开发您的代码和测试用例，运行测试用例来验证您的修改是正确的。
+
+提交代码到您的分支上。
+
+如果您的更改有多个提交，请使用`git rebase -i master`将它们压缩为单个提交，并将代码更新到主线上的最新版本。
+
+然后将您的提交推送到GitHub上，并从您的分支创建一个pull请求到QSQL主分支，committer将会检查您的更改。
+
+在提交之后，pull request可能需要更新，原因如下：
+
+- 您在提交pull request之后发现了一个问题
+- reviewer要求进一步修改
+
+为了更新pull请求，需要在分支中提交更改，然后将提交推到GitHub。我们鼓励您在现有提交的基础上使用常规（非基于重新构建）提交。
+
+当将更改推送到GitHub时，您应该避免使用`--force`参数及其替代方法。您可以选择在某些条件下强制推行您的更改：
+
+- 最近一次的pull request的提交在10分钟之内，并且没有关于它的未决讨论
+- reviewer明确要求您执行一些需要使用`--force`选项的修改
diff --git a/docs/zh/deployment/deployment.md b/docs/zh/deployment/deployment.md
@@ -1,11 +1,11 @@
 [English](../../deployment/deployment.md)|[中文](./deployment.md)
 
 
-## 部署指南
+# 部署指南
 
 (引言)本页面将提供Quicksql支持的数据源和引擎的配套版本和依赖包调整方式，此外，元数据的管理方式也将被提及。
 
-### 数据源管理
+## 数据源管理
 
 Quicksql提供默认的数据源客户端版本，以下是版本关系表，用户可以自行替换Jar包更替。
 
@@ -29,7 +29,7 @@ $ cp mysql-connector-java-8.0.18.jar ./
 $ ../bin/quicksql -e "SELECT * FROM TABLE_IN_MySQL8"
 ``````
 
-### 计算引擎管理
+## 计算引擎管理
 
 Quicksql使用的计算引擎可以由用户自定义参数，参数可以在./conf/qsql-runner.properties中修改：
 
@@ -52,11 +52,11 @@ Quicksql使用的计算引擎可以由用户自定义参数，参数可以在./c
 | ------------- | ------- | ------- |
 | 待补充        | 待补充  | 待补充  |
 
-### 元数据管理
+## 元数据管理
 
 Quicksql使用一个独立的存储来存放各类数据源的元数据及配置信息，默认的元数据存储为Sqlite，一个文档数据库，在普通开发环境下可以使用。如果对并发能力有更高的要求，可以更换元数据存储为MySQL等，采用通用的JDBC标准，可参考以下配置：
 
-#### 元数据参数
+### 元数据参数
 
 | Property Name               | Default                | Meaning                                                      |
 | --------------------------- | ---------------------- | ------------------------------------------------------------ |