贡献指南

你好!很高兴你有兴趣为 Fresns 做贡献。在提交您的贡献之前,请务必花点时间阅读以下介绍:

技术框架

框架用途
Composeropen in new window软体包管理系统
Laravel Frameworkopen in new window主程序框架
Laravel Langopen in new window框架语言包
Bootstrapopen in new window内置前端框架
Bootstrap Iconsopen in new window内置前端图标字体库
jQueryopen in new window内置 JS 库
Select2open in new window内置 Select2 选择框
Base64 JSopen in new window内置 Base64 转码器
VuePressopen in new windowFresns 官网生成器
数据库MySQL 5.7MySQL 8.x
排序规则utf8mb4_unicode_520_ciutf8mb4_0900_ai_ci
存储引擎InnoDBInnoDB

协作规范

指南来源
12-factorsopen in new windowAdam Wiggins
约定式提交规范open in new windowConventional Commits
语义化版本号open in new windowGravatars
中文文档编写指南open in new window唐杰
英文文档编写指南open in new windowVue.js

辅助工具

工具说明
StyleCIopen in new window编码风格修正器,帮助 Fresns 统一编码风格
Sentryopen in new window程序性能监控服务,帮助 Fresns 诊断、修复和优化代码的性能
Huntropen in new window漏洞赏金平台,帮助 Fresns 发现安全问题

编码风格

为了保持 Fresns 代码库的整洁性和一致性,我们有着一套遵循的编码风格。如果您对此有疑问,请阅读相关源代码。

您不用担心自己的代码风格是否完美,在合并 Pull Request 后,StyleCIopen in new window 会先自动修正任何风格的代码,然后再合并到 Fresns 项目仓库。这使得我们可以专注在贡献的内容本身,而非代码风格上。

Fresns 遵循 PSR-2open in new window 编码规范和 PSR-4open in new window 自动加载规范。我们尽可能地使用 PHP 7 类型提示和返回类型声明,我们也使用 PHPDocopen in new window 提供内联文档。请您尽量在贡献时模仿其他代码库使用的风格。

  • 命名空间应当是单数(例如:Fresns\Discussion,而非 Fresns\Discussions
  • 接口命名应当以 Interface 结尾(例如:MailableInterface
  • 抽象类命名应当以 Abstract 开头(例如:AbstractModel
  • Trait 命名应当以 Trait 结尾(例如:ScopeVisibilityTrait
  • 状态命名,有状态迁移关系使用 state,没有状态迁移关系使用 status
    • state 交通灯状态: red -> green -> yellow
    • status 付款结果: success / failed

数据库风格

的命名规则如下:

  • 使用复数形式(languages
  • 多个单词之间用下划线分隔(session_tokens
  • 对于关系表,请将两个表名用单数的形式连接起来,并按字母顺序排列。(例如:discussion_user

字段 的命名应当根据其数据类型而定:

  • DATETIME 或 TIMESTAMP:{动词}_at(例如:created_at,read_at)或 {动词}_until(例如:suspended_until)
  • INT 用于计数:{名词}_count(例如:comment_count,word_count)
  • 外键:{动词}_{实体对象}_id(例如:hidden_user_id)
    • 动词可以使用具有相同意义的主键等替代(例如:帖子作者可以是 user_id)
  • 布尔值:is_{形容词}(例如:is_locked)
  • 标志性时间值必须采用 TIMESTAMP 类型字段,确保支持时区请求(例如:创建时间、更新时间、操作行为时间)。
  • 颜色值字段统一存储为 6 位十六进制颜色值。

贡献者许可协议

通过向 Fresns 贡献你的代码,你授予 Fresns 团队你的所有相关知识产权(包括版权、专利和任何其他权利)的非独占的、不可撤销的、全球性的、免版税的、可再许可且可转让的许可,以便我们在任何许可条款下使用、复制、准备衍生作品、分发、公开执行和展示此等贡献,包括但不限于以下条款:(a) 开放源码许可证,如 Apache-2.0 许可证;以及 (b) 二进制、专有或商业许可证。除本协议授权的许可外,你保留与此等贡献有关的所有权利、所有权和利益。

你确认,你能够授予我们这些权利。你声明,你在法律上有权授予上述许可。如果你的雇主对你所创造的知识产权拥有权利,你声明你已获得许可代表该雇主做出贡献,或者你的雇主已放弃了此等贡献的以上权利。

你声明,此等贡献是你的原创作品,而且据你所知,没有其他人主张或有权主张此等贡献有关的任何发明或专利的任何权利。你还声明,无论是通过签订协议还是其他方式,你都没有任何与本许可条款相冲突的法律义务。

Fresns 团队确认,除非本协议中有明确的描述,你提供的任何贡献都是以「现状」为基础的,不附带任何形式的无论明示或暗示的保证或条件,包括但不限于任何关于所有权、非侵权、适销性或特定用途的适用性的保证或条件。

/*
 * Fresns
 * Copyright (C) 2021-Present 唐杰
 * Released under the Apache-2.0 License.
 */
1
2
3
4
5