Contributing Guide

Hi! I'm really excited that you are interested in contributing to Fresns. Before submitting your contribution, please make sure to take a moment and read through the following guidelines:

协作规范

GuideDescription
12-factorsopen in new windowAdam Wiggins
约定式提交规范open in new windowConventional Commits
语义化版本号open in new windowGravatars
中文文档编写指南open in new window唐杰
英文文档编写指南open in new windowVue.js
查看 Commit 类型介绍
  • 日志的所有内容都使用 ASCII 字符,不要用中文或者 emoji,这样最大化兼容性,也便于程序处理。总体结构如下:
类型(可选的范畴): 简短描述

可选的详情

可选的注解
  • 下面是一个完整的示例:
feat(auth): increase length of new API key

the length is increased from 24 to 32 for new API keys

close #12
类型说明
featfeature - 所有实现新功能、新行为的 commit 都属这个类型
fix修正缺陷的 commit
chore日常维护性的改动,例如 linter 的配置等
test与测试有关的改动
refactor不改变行为的对代码结构的改进
style对代码风格的修正(仅限缩进、空行一类的简单改动,对结构有影响的用 refactor)
cosmcosmetic - 不改变行为的对界面的纯视觉上的改动
docs对文档的改进,包括对外文档和代码注释
build和构建流程、持续集成等有关的改动

Help Tools

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

Coding Style

In order to keep the Fresns codebase clean and consistent, we have a number of coding style guidelines that we follow. When in doubt, read the source code.

Don't worry if your code styling isn't perfect! StyleCIopen in new window will automatically merge any style fixes into Fresns repositories after pull requests are merged. This allows us to focus on the content of the contribution and not the code style.

Fresns follows the PSR-2open in new window coding standard and the PSR-4open in new window autoloading standard. On top of this, we conform to a number of other style rules (opens new window). We use PHP 7 type hinting and return type declarations where possible, and PHPDocopen in new window to provide inline documentation. Try and mimic the style used by the rest of the codebase in your contributions.

  • Namespaces should be singular (eg. Fresns\Discussion, not Fresns\Discussions)
  • Interfaces should be suffixed with Interface (eg. MailableInterface)
  • Abstract classes should be prefixed with Abstract (eg. AbstractModel)
  • Traits should be suffixed with Trait (eg. ScopeVisibilityTrait)
  • "status" or "state"
    • status is used to describe an outcome of an operation (e.g. success/fail).
    • state is used to describe a stage in a process (e.g. pending/dispatched).

Database Style

Tables should be named as follows:

  • Use plural form (languages)
  • Separate multiple words with underscores (session_tokens)
  • For relationships tables, join the two table names in singular form with an underscore in alphabetical order (eg. discussion_user)

Columns should be named according to their data type:

  • DATETIME or TIMESTAMP: {verbed}_at (eg. created_at, read_at) or {verbed}_until (eg. suspended_until)
  • INT that is a count: {noun}_count (eg. comment_count, word_count)
  • Foreign key: {verbed}_{entity}_id (eg. hidden_user_id)
    • Verb can be omitted for primary relationship (eg. post author is just user_id)
  • BOOL: is_{adjective} (eg. is_locked)
  • 标志性时间值必须采用 TIMESTAMP 类型字段,确保支持时区请求(例如:创建时间、更新时间、操作行为时间)。
  • 颜色值字段统一存储为 6 位十六进制颜色值。

Contributor License Agreement

By contributing your code to Fresns you grant the Fresns Foundation (Stichting Fresns) a non-exclusive, irrevocable, worldwide, royalty-free, sublicensable, transferable license under all of Your relevant intellectual property rights (including copyright, patent, and any other rights), to use, copy, prepare derivative works of, distribute and publicly perform and display the Contributions on any licensing terms, including without limitation: (a) open source licenses like the MIT license; and (b) binary, proprietary, or commercial licenses. Except for the licenses granted herein, You reserve all right, title, and interest in and to the Contribution.

You confirm that you are able to grant us these rights. You represent that You are legally entitled to grant the above license. If Your employer has rights to intellectual property that You create, You represent that You have received permission to make the Contributions on behalf of that employer, or that Your employer has waived such rights for the Contributions.

You represent that the Contributions are Your original works of authorship, and to Your knowledge, no other person claims, or has the right to claim, any right in any invention or patent related to the Contributions. You also represent that You are not legally obligated, whether by entering into an agreement or otherwise, in any way that conflicts with the terms of this license.

The Fresns Foundation acknowledges that, except as explicitly described in this Agreement, any Contribution which you provide is on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.

/*
 * Fresns
 * Copyright (C) 2021-Present Jarvis Tang
 * Released under the Apache-2.0 License.
 */