Merge pull request #1 from HelloGitHub-Team/master

Synchronous update

Author: 719923505

README.md

@@ -1,26 +1,52 @@
-# HelloGitHub-Team 协作开发须知
+# HelloGitHub-Team wiki
+
+接不完的需求？堆砌没有灵魂的代码？做的功能没人用？来，加入 HG 修改、增加你想要的功能，我们不需要产品经理，最后让你的代码跑在 HelloGitHub.com 让更多人使用和看到。
+
 ## 一、项目介绍
-编程是让流程变得更加简单、方便的途径，以下项目都是为了方便更好的发掘、推荐 GitHub 上优秀的开源项目。
+本项目是 HelloGitHub-Team 开源组织的须知文档，想加入、刚加入我们的小伙伴请一定要**认证阅读**本项目中涵盖的文档。
 
-- [官网](https://hellogithub.com)、[HelloGitHub 开源项目](https://github.com/521xueweihan/HelloGitHub)
-- 前端项目：[taichi](https://github.com/HelloGitHub-Team/taichi) 可视化前端项目
-- 后端项目：[hellogithub.com](https://github.com/521xueweihan/hellogithub.com) 目前正在基于 fastapi 重构中（完成后开源）
+*Tips： 有任何问题直接提 PR 修改。*
 
-开源项目协作开发是一件自由且松散的事情，但是项目工程又是一件严谨的事情。所以需要一些规范来让事情有条不紊的进展和推进，所以下面列举了一些一起协作开发之前需要知道的事情和规范。
+## 二、须知部分
+开源项目协作开发是一件自由且松散的事情，但是项目工程又是一件严谨的事情。所以需要一些规范来让事情有条不紊的进展和推进，所以下面列举了一些一起协作开发之前需要知道的事情和遵守的规范。
 
-## 二、规范
 1. [内容编写规范](doc/copywriting.md)
-2. [接口文档](doc/api.md)
-3. [Git 工作流]()
-4. [项目进度管理](doc/projects.md)
+2. [协作开发须知](doc/cooperation.md)
+3. [接口文档](doc/api.md)
+
+## 三、我们的项目
+以下项目都是为了方便更好的发掘、推荐 GitHub 上优秀的开源项目。
+
+- [官网](https://hellogithub.com)
+- [HelloGitHub](https://github.com/521xueweihan/HelloGitHub)：鼻祖项目，发布最新月刊、历史月刊集合的项目。
+- [wiki](https://github.com/HelloGitHub-Team/wiki)：团队成员必读的 wiki 文档包含：书写规范、开发规范、接口文档。
+- [taichi](https://github.com/HelloGitHub-Team/taichi)：太极，数据可视化前端，逐步替代官网的前端项目。
+- [hellogithub.com](https://github.com/521xueweihan/hellogithub.com)：后端项目，包含网站的服务端、管理后台、Issues 机器人、三方接口，目前正在基于 fastapi 重构中（完成后开源）。
+
+
+## 四、加入我们
+目前我们正处于前后端分离、重构的阵痛期，每个人的时间都很宝贵，请阅读完上面的信息后再联系我。
+
+**不欢迎需要督促、伸手党，确定想要业余时间和 HG 一起做让你骄傲、有意义的事情后再联系我。**
+
+任何人都可以在 HG-Team 中创建有价值、有趣的项目，你将会成为这个项目的负责人。作为负责人请让项目持续的更新下去，越来越有价值。我不在乎起点，更看重的是天花板。HG 会作为“开源项目孵化器”，让你的项目被更多人所熟知和喜欢～
 
-## 三、加入我们
-目前项目整体正处于前后端分离、重构的阵痛期，每个人的时间都很宝贵，请阅读完已知有限信息后。不欢迎需要督促、伸手党，确定要和我们一起做一些让你骄傲和有意义的事情后再联系我。
+优秀的项目应该包含：
+1. 详细的 README 文件
+    - 言简意赅说明项目的用途和亮点
+    - 详细的安装、运行步骤、运行效果图
+    - 包含文档、技术栈和架构图
+    - 能用图、少写字
+2. 良好的协作规范、代码风格检测和注释
+3. 完整的依赖三方库或项目明细（或者注明用的包管理工具）
+4. 尽可能高的测试覆盖率
+5. 简单的部署方式和自动的 CI/CD
+6. 开源协议
 
-请思考一个问题：你坚持最久的一件事情是什么，坚持了多长时间？
+**最后**：请思考一个问题：你坚持最久的一件事情是什么，坚持了多长时间？
 
-微信：xueweihan（备注：前端 or 后端），然后把你的经历告诉我。
+微信：xueweihan（备注：前端 or 后端），然后请开始你的故事。
 
 
-## 四、声明
+## 五、声明
 <a rel="license" href="https://creativecommons.org/licenses/by-nc-nd/4.0/deed.zh"><img alt="知识共享许可协议" style="border-width: 0" src="https://licensebuttons.net/l/by-nc-nd/4.0/88x31.png"></a><br>本作品采用 <a rel="license" href="https://creativecommons.org/licenses/by-nc-nd/4.0/deed.zh">署名-非商业性使用-禁止演绎 4.0 国际</a> 进行许可。

doc/api.md

@@ -469,10 +469,10 @@ PATH：`GET /api/v1/traffic/periodical/detail/`
 比如：要请求 2019年11月16日 的数据，则 start_time 为 2019年11月16日00:00:00，end_time 为 2019年11月17日00:00:00
 
 **Tips：** 默认返回昨天的数据，时间戳单位为秒。
+
 **Tips：** 如果两者时间间隔超过30天，以开始时间为准，结束时间为开始时间往后推30天。
-**Tips：** 排序列:文档中枚举第一个字段是默认的排序字段
 
-### 4.1 获取某搜索时间段内的语言分类
+### 4.1 获取语言分类
 
 PATH：`GET /api/v1/daily/langs/`
 
@@ -495,20 +495,22 @@ PATH：`GET /api/v1/daily/langs/`
 }
 ```
 
-### 4.2 获取 GitHub 上收集项目在某个时间段某种语言的详细数据
+### 4.2 获取 GitHub Source 上收集项目的详细数据
 
-PATH：`GET /api/v1/daily/detail/`
+PATH：`GET /api/v1/daily/report/`
 
 参数：
 
 | 名称     | 必须  | 类型 | 描述 | 
 | ------- | ----- | ----- | ----- |
 | start_time | 否 | int | 开始时间戳 |
-| end_time | 否  | int | 结束时间戳 |
-| lang    | 否  | string | 语言 |
-| page | 否 | int | 页数默认为第一页 |
-| order    | 否 | string | 排序列（stars、lang、repo_pushed_time）|
-| asc    | 否 | int | 默认为 0 降序，1 为升序 |
+| end_time   | 否 | int | 结束时间戳 |
+| lang       | 否 | string | 语言 |
+| page       | 否 | int | 页数默认为第一页 |
+| order      | 否 | string | 排序列（stars、forks、repo_pushed_time）|
+| asc        | 否 | int | 默认为 0 降序，1 为升序 |
+
+**Tips：** 排序列文档中枚举第一个字段是默认的排序字段
 
 响应：
 ```
@@ -517,24 +519,23 @@ PATH：`GET /api/v1/daily/detail/`
   "payload": {
     "start_time": 1573713003,
     "end_time": 1573723003,
-    "lang": "",  #默认为空,即不区分语言
+    "primary_lang": "",  #默认为空,即不区分语言
     "current_page": 1,  #当前页码
     "page_count": 10,  #总页数
     "order": "stars",
     "asc": 0,
+    "count": 10,  #项目总数
+    "page_size": 10,
     "data": [
       {
-        "repo_id": 13,  #项目唯一id
-        "name": "HelloGitHub",  #项目名称
-        "desc": "分享有趣的GitHub项目", #项目描述
-        "star": 3000,  #项目star数
-        "lang": "Python",  #项目主语言
-        "url": "https://github.com/521xueweihan/HelloGitHub",  #项目地址
-        "repo_pushed_time": 1573713003,
-        "volume_id": 1,
-        "volume_name": "01",  #月刊期数,
-        "category_id": 7,
-        "category_name": "Go 项目"        
+        "description": "Consul is a distributed, highly available, and data center aware solution to connect and configure applications across dynamic, distributed infrastructure.", 
+        "is_chinese": false, 
+        "name": "consul", 
+        "primary_lang": "Go", 
+        "repo_pushed_time": 1592275530, # 项目最后一次活动时间
+        "stars": 19431, 
+        "forks": 332, 
+        "url": "https://github.com/hashicorp/consul"
       },
       ...
     ]

doc/cooperation.md

@@ -0,0 +1,46 @@
+# 协作开发须知
+技术是为了让业务更加流畅和高效。
+
+所以在设计方案和开发之前，一定要对需要解决的实际问题来龙去脉了解清楚，做这个问题的“主人”。
+
+## 一、原则
+开源项目的开发不要做成和工作时候一样，接需求。要自己去找需要优化的点、认同需要解决的问题，这样要做的东西才是自己想做的，才能感受到做开源的乐趣：写自己感兴趣的代码，用自己觉得酷的技术。
+
+因为开源是多人协作开发的形式，所以流程很重要否则会很乱无法跟踪进度和管理。下面是 HG 的协作开发流程，需要各位参与开发的小伙伴认证阅读并遵守。
+
+大体上分为：
+- 任务管理：创建任务、任务模版、管理同步项目进度
+- 开发流程：Git 工作流、遵守参与项目的代码规范
+
+## 二、流程（概述流程，详尽步骤请阅读项目的 README）
+为了方便跟踪记录做的事情，我们一定要按照流程走，这样才不会丢掉任务、让任务停滞。
+
+1. 参与到某个项目后，找对应的项目负责人申请 GitHub 项目权限、官网后台权限、Token 等。
+2. 确定要做的功能后，在参与项目的 project 中创建任务，并放到对应的状态列下。内容模版如下：
+    ```
+    #### 任务名称：
+    - [ ]拆分任务1
+    - [ ] ...
+    ---
+    （分割线下是 Bug、问题修复、优化任务的记录）
+    - [ ]修复 xxx 问题
+    
+    Begin：2019-11-20（开始时间）
+    End：？（完成时间，自行安排，如有延期在群里说一下，然后再加一行新的 End：时间）
+    @GitHub用户名（开发者）
+    ```
+3. 开发时具体到某个项目，会有对应的依赖库、技术栈、代码规范、安装环境流程，请自行认真阅读，如遇问题找 Team 中人员请教。
+4. 写代码的第一步请基于 dev 分支创建：feature_功能描述 分支，进行开发。
+5. 开发过程中，可自行思考需要加入的功能（前提是正确理解要解决的问题），有新的想法可以找最初问题的提出者讨论，达成一致后，搞就完事儿了。
+6. 提交代码前，请自行测试完成后。提交 feature 合并到 dev 分支的 PR，并分配给其他项目成员和项目负责人进行 review。（可在群里提示）
+7. 请大家积极、及时参与 review 中，同时管理上述创建的任务状态。
+
+**注意**：写代码不要图一时之快，做到可维护、可阅读、有理可依、对应文档和注释及时更新和同步。工作中写的坑还不够多吗？做自己的项目，需要对自己要求高一点、再高一点。
+
+## 三、写给项目负责人
+一个人的代码威力有限，创建维护优秀的项目，凝聚更多优秀的人，让一切变得顺理成章。
+
+让项目内的人开心的协同开发、积极的讨论，是一个项目负责人最应该做的事情。所以需要保证项目有意思、代码质量优秀、标准的规范、协作流程简单但不简陋，最后要保证项目持续推进。
+
+只要项目足够优秀，优秀的人自然是会欣然加入的。
+