Skip to content

Latest commit

 

History

History
213 lines (172 loc) · 10.8 KB

CONTRIBUTING-CH.md

File metadata and controls

213 lines (172 loc) · 10.8 KB
Raw

Contributing

非常感谢贡献 Davinci！在参与贡献之前，请仔细阅读以下指引。

贡献范畴

Bug 反馈与修复

我们建议无论是 Bug 反馈还是修复，都先创建一个 Issue 来仔细描述 Bug 的状况，以助于社区可以通过 Issue 记录来找到和回顾问题以及代码。Bug 反馈 Issue 通常需要包含完整描述 Bug 的信息以及可复现的场景，这样社区才能快速定位导致 Bug 的原因并修复它。包含 #bug 标签的打开的 Issue 都是需要被修复的。

功能交流、实现、重构

在交流过程中，详细描述新功能（或重构）的细节、机制和使用场景，能够促使它更好更快地被实现。如果计划实现一个重大的功能（或重构），请务必通过 Issue 或其他方式与核心开发团队进行沟通，这样大家能以最效率的方式来推进它。包含 #feature 标签的打开的 Issue 都是需要被实现的新功能，包含 #enhancement 标签的打开的 Issue 都是需要改进重构的功能。

Issue 答疑

帮助回答 Issue 中的使用问题是为 Davinci 社区做贡献的一个非常有价值的方式；社区中总会有新用户不断进来，在帮助新用户的同时，也可以展现你的专业知识。

文档改进

Davinci 用户手册文档在 docs/ 目录下，我们使用了 jekyll 作为 Davinci 的文档服务，可以编辑目录里的 Markdown 文件来对文档做改进。

国际化

非常抱歉，Davinci 目前仅支持中文语言；但项目前端依赖包含 react-intl，代码结构上也支持国际化，欢迎对其他语言进行贡献。

贡献流程

分支结构

Davinci 源码可能会产生一些临时分支，但真正有明确意义的只有以下三个分支：

  • dev-0.3: 默认分支，主要开发分支，需要注意，dev-0.3分支代码不保证可用性，请谨慎使用到生产；
  • master: 最近一次稳定 release 的源码，偶尔会多几次 hotfix 提交；
  • dev-0.2: 0.2 版本源码，目前 0.2 版本已经停止更新，如有 0.2 版本使用者或是需要进行二次开发的用户可以参考此分支。

开发指引

Davinci 前后端代码共用同一个代码库，但在开发上是分离的。在着手开发之前，请先将 Davinci 项目 fork 一份到自己的 Github Repositories 中， 开发时请基于自己 Github Repositories 中的 Davinci 代码库进行开发。

如果你计划给 Davinci 贡献代码，我们建议克隆 dev-0.3 分支来开发，这样在向 Davinci 主项目提交 PR 时合并冲突的可能性会小很多。

git clone https://github.com/yourname/davinci.git

如果你只是基于稳定功能做一些定制化满足使用需要，我们建议克隆 master 分支来开发。

git clone https://github.com/yourname/davinci.git --branch master

前端

前端源代码在 webapp/ 目录中；davinci-ui/ 目录为编译后的前端文件

目录结构
├── app              # 主应用源码
  ├── assets           # 资源文件
  ├── components       # 通用组件
  ├── containers       # 路由容器组件
  ├── utils            # 通用实用方法
  └── app.tsx          # 主应用入口
├── internals        # 开发工程文件
├── libs             # 改动后的项目依赖
├── server           # 开发服务器
├── share            # 分享页源码
└── package.json
开发
npm install
npm start
Lint
npm run lint
Test
npm run test
打包
npm run build

后端

用户配置在项目根目录 /config/ 下，项目启动脚本和升级补丁脚本在项目根目录 /bin/ 下， 后端代码及核心配置在 server/ 目录下, 日志在项目根目录 /log/ 下。注意：此处所指项目根目录都指环境变量 DAVINCI3_HOME 所配置的目录，在使用 IDE 开发过程中也需要配置环境变量，如 Idea 关于环境变量加载的优先级：Run/Debug Configurations 中配置的 Environment variables —> IDE缓存的系统环境变量。

目录结构

脚本

├── bin                   # 脚本目录
  ├── migration             # 较大版本变动迁移脚本目录
  ├── patch                 # 数据库补丁
  	 ├── 001_beta5.sql        # 已发布补丁（命名规则：“序列_版本”）
  	 └── beta.sql             # 当期未发布补丁（固定名称）
  ├── build.sh
  ├── davinci.sql           # 完整系统数据库脚本（包含所有补丁）
  ├── initdb.bat            # 针对 Windows 环境的初始化数据库批处理脚本
  ├── initdb.sh             # 针对 Linux、Mac 环境的初始化数据库 Shell 脚本
  ├── restart-server.sh     # 针对 Linux、Mac 环境的重启服务脚本
  ├── run.bat               # 针对	Windows 环境的服务启停核心脚本						
  ├── start.bat             # 针对 Windows 环境的服务启动脚本
  ├── start-server.sh       # 针对 Linux、Mac 环境的服务启动脚本
  ├── stop.bat              # 针对 Windows 环境的服务停止脚本
  └── stop-server.sh        # 针对 Linux、Mac 环境的服务停止脚本

用户配置

├── config                          # 用户配置目录
  ├── application.yml.example         # 应用配置模板
  ├── datasource_driver.yml.example   # 自定义数据源配置模板
  └── logback.xml                     # 日志配置

代码目录结构

├── server                                  # Server 代码根目录
   ├── src                                    # 源码
  	  ├── main
  	  	 ├── java
  	  	 	└── edp
  	  	 	   ├── core                             # 核心配置及通用代码
  	  	 	   ├── davinci                          # Davinci 业务代码 
  	  	 	   ├── DavinciServerApplication         # 系统启动类
  	  	 	   └── SwaggerConfiguration             # Swagger 配置类
  	  	 └── resources
  	  	 	├── generator
  	  	 	├── mybatis                           # mybatis mapping 目录
  	  	 	├── templates                         # 邮件、Sql 模板目录 
  	  	 	├── application.yml                   # 系统核心配置文件
  	  	 	└── banner.txt
  	  └── test                                # 测试代码目录
   └── pom.xml                              # Davinci Server maven 配置文件，继承自项目根目录pom.xml

日志目录

├── logs        # 日志根目录
  ├── sys         # 系统日志目录
  └── user        # 用户日志目录
  	 ├── opt        # 用户操作日志
  	 └── sql        # 用户Sql日志
环境变量

配置系统环境变量或 IDE 环境变量 DAVINCI3_HOME，推荐优先使用 IDE 环境变量。

数据库
  1. 自行创建 Davinci 系统数据库；
  2. 修改 bin/initdb.sh 或 bin/initdb.bat 中的数据库相应信息并执行 或 直接在数据库客户端导入 bin/davinci.sql。
配置文件

重命名 config/ 目录下 application.yml.example 文件为 application.yml，并配置相关属性。

打包
  1. 打完整 release 包需要修改根目录下 /assembly/src/main/assembly/assembly.xml 中相关版本信息，然后在根目录下执行: mvn clean package 即可；
  2. 打 server 包可直接在 server/ 目录下执行 mvn clean package。

Pull Request 指引

  • 如果你还不知道怎样向开源项目发起 PR，请参考这篇说明
  • 无论是 Bug 修复，还是新功能开发，请将 PR 提交到 dev-0.3 分支。
  • PR 和提交名称遵循 <type>(<scope>): <subject> 原则，详情可以参考阮一峰的 Commit message 和 Change log 编写指南 这篇文章。
  • 如果 PR 中包含新功能，理应将文档更新包含在本次 PR 中。
  • 如果本次 PR 尚未准备好合并，请在名称头部加上 [WIP] 前缀（WIP = work-in-progress）。
  • 所有提交到 dev-0.3 分支的提交至少需要经过一次 Review 才可以被合并

Review 标准

在贡献代码之前，可以了解一下什么样的提交在 Review 中是受欢迎的。简单来说，如果一项提交能带来尽可能多增益和尽可能少的副作用或风险，那它被合并的几率就越高，Review 的速度也会越快。风险大、价值低的提交是几乎不可能被合并的，并且有可能会被拒绝连 Review 的机会都没有。

增益

  • 修复导致 Bug 的主要原因
  • 添加或修复一个大量用户亟需的功能或问题
  • 简单有效
  • 容易测试，有测试用例
  • 减少复杂度以及代码量
  • 经社区讨论过的、确定需要改进的问题

副作用和风险

  • 仅仅修复 Bug 的表面现象
  • 引入复杂度高的新功能
  • 为满足小众需求添加复杂度
  • 改动稳定的现有API或语义
  • 导致其他功能不能正常运行
  • 添加大量依赖
  • 随意改变依赖版本
  • 一次性提交大量代码或改动

Reviewer 注意事项

  • 请使用建设性语气撰写评论
  • 如果需要提交者进行修改，请明确说明完成此次 Pull Request 所需要修改的所有内容
  • 如果某次 PR 在合并后发现带来了新问题，Reviewer 需要向 PR 作者联系并沟通解决问题；如果无法联系到 PR 作者，Reviewer 需要将此次 PR 进行还原

贡献进阶

关于 Committers（Collaborators）

如何成为 Committer

如果你对 Davinci 代码有过颇具价值的 PR 并且被合并，你可以在这个 Issue 下评论，或是通过官方微信群联系核心开发团队申请成为 Davinci 项目的 Committer；核心开发团队和其他 Committers 将会一起投票决定是否允许你的加入，如果得到足够票数，你将成为 Davinci 项目的 Committer。

Committer 的权利

  • 可以加入官方开发者微信群，参与讨论和制定开发计划
  • 可以对 Issue 进行管理，包括关闭、添加标签
  • 可以创建和管理项目分支，master、dev-0.3、dev-0.2 分支除外
  • 可以对提交到 dev-0.3 分支的 PR 进行 Review
  • 可以申请成为 Committee 成员

关于 Committee

如何成为 Committee 成员

如果你是 Davinci 项目的 Committer，并且你贡献的所有内容得到了其他 Committee 成员的认可，你可以申请成为 Davinci Committee 成员，其他 Committee 成员将会一起投票决定是否允许你的加入，如果全票通过，你将成为 Davinci Committee 成员。

Committee 成员的权利

  • 可以合并其他 Committers 和贡献者提交到 dev-0.3 分支的 PR