跳到主要内容

建设 Flarum

有兴趣参与 Flarum 的建设吗？非常好，正是有了这么多人的共同付出，Flarum 才有了今天。报告错误 或拉取请求，你想做什么都没问题！

贡献前，请阅读 行为准则。

本文档面向贡献代码的开发者，如果您还不熟悉 Flarum 的代码结构，建议先阅读 进阶：起步 了解 Flarum 的工作原理。

为什么是 Flarum？#

⚡ 创造积极影响。 成千上万的站长选择了 Flarum，数以万计的用户正在使用 Flarum。参与 Flarum 的开发，您的代码能实实在在影响到每一个人。

🔮 塑造美好未来。 议题涌现，时间却永远有限。如果您愿意挑战自我，为喜欢的功能和议题付诸行动，您所想所要的才可能尽快实现，这也是获得影响力的快捷通道。去看看 核心开发团队 制定的路线图和里程碑吧，从简单的做起，一步一步才是真理。

🧑‍💻 提升自我能力。 Flarum 的代码是现代化、工程化，整洁的。在外观、底层设计、性能和可扩展性方面，Flarum 还有许多有趣的、具有挑战性的问题需要解决。如果您还是学生，或刚刚进入社会，参与建设 Flarum 绝对是锻炼自己的绝佳途径。

🎠 享受纯粹快乐！ 对代码有兴趣的人来说，开发中的挑战和成就能带来巨大的乐趣，我们也是如此。我们的论坛 和 Discord 服务器 都很活跃，您可以随时提问，随时交流。

如何开始#

查看我们规划的 里程碑，了解需要做的事情。您可以查看 「Good first issue」 标签中的议题，它们都比较容易上手。无论您遇到什么困难都不要怕，敞开了问我们，我们每个人都是这样子成长起来的。

如果您想着手进行某项工作，请先在相关议题中评论或发起新议题告知我们，以免事倍功半。

Flarum 是基于扩展程序的理念打造的，我们强烈建议您在开发核心和原生扩展时始终以 我们的扩展文档 为参考，从 核心概念 开始上手，对扩展理念做一个系统的了解。

开发准备#

设置本地代码库#

flarum/flarum 是整个应用的「框架」，它通过 Composer 将 核心 flarum/core 和 相关应用程序 下载到本地。为了降低开发时的工作量，我们建议您复刻它们，并克隆到 Composer 本地路径存储库：

git clone https://github.com/flarum/flarum.gitcd flarum
# 为 Flarum 程序包设置 Composer 本地路径存储库composer config repositories.0 path "packages/*"git clone https://github.com/<username>/core.git packages/coregit clone https://github.com/<username>/tags.git packages/tags # 克隆核心和标签扩展，以此类推

接着，将 composer.json 中的 minimum-stability 改为 dev，这样 Composer 才能接受本地副本中的开发版本。

最后，运行 composer install 从本地路径存储库完成本地 Flarum 的安装。

准备好本地环境后，请务必打开 config.php 中的 debug 调试模式，并在 PHP 配置中将 display_errors 设置为 On。这样您就能同时看到 Flarum 和 PHP 的详细报错内容。同时，调试模式下，每一次请求都将强制重新编译 Flarum 的静态资源。因此，在扩展程序的 JavaScript 或 CSS 发生变更后，您无需运行 php flarum cache:clear 命令主动清除缓存。

Flarum 的前端代码使用 ES6 规范，然后进行降级处理。在开发过程中，您需要使用 Node.js 重新编译 JavaScript。提交拉取请求时，请在 gitignore 中忽略 dist 文件夹，当变更合并到 master 分支时，一切都会自动处理。

cd packages/core/jsnpm installnpm run dev

对于扩展程序，过程是一样的。

cd packages/tags/jsnpm installnpm link ../../core/jsnpm run dev

开发工具#

复刻并克隆需要用到的存储库后，您需要配置本地 Web 环境，以便进行测试。 Flarum 目前不提供开发服务器，所以您需要为本地 Flarum 配置 Apache/NGINX/Caddy 等服务器程序。

或者，使用诸如 Mac 上的 Laravel Valet 或 Windows 上的 XAMPP 等工具，也可以使用 Linux 的 Docker-Flarum 来运行本地 Flarum。

你也可以参考多数贡献者的选择：PHPStorm 或 Visual Studio Code。

开发流程#

一个典型的工作流程是这样的：

  1. 🧭 理清思路，做好计划。

  2. 🌳 建立分支，选择合适的分支，复刻然后开始。

    • Bug 修复 应当提交到最新的稳定分支。
    • 次要 并与当前 Flarum 版本兼容的功能开发可以提交到最新的稳定分支。
    • 主要 功能应当始终提交到 master 分支，新版本将基于此分支发布。
    • 在内部，我们使用 <姓名缩写>/<功能简述> 的格式命名分支（例如：tz/refactor-frontend）。

  3. 🔨 编写代码，开始动手。

  4. 🚦 测试代码，查漏补缺。

    • 修复错误或添加功能时，请根据需要添加单元测试。
    • 在相关包文件夹中使用 vendor/bin/phpunit 运行测试套件。
    • 阅读 这里 获取更多测试 Flarum 的信息。

  5. 💾 提交代码，附上说明信息。

    • 通常来说，您的提交应当能够解决了一个现有的议题，请在提交消息中另起一行填写议题号，如「Fixes #123」，其中 123 就是议题号。
    • 撰写一个 优秀的提交消息。

  6. 🎁 请求合并，在 GitHub 中提交拉取请求。

    • 填写拉取请求的模板。
    • 对于视觉上的更改，请附上截图或 GIF 展示。
    • 不要提交 npm 的 dist 文件夹，请求合并时一切都会自动编译。

  7. 🤝 合作共赢，等待 Flarum 团队批准。

    • 团队成员将审阅您的代码。我们可能会提出一些修正、改进或替代方案，但对于改动较小的请求，一般会很快合并。
    • 请您在处理好我们反馈的内容后，追加提交，不要覆盖或整合提交，我们会在合并时替您完成这些操作。

  8. 🕺 大功告成，贡献成功。

代码风格#

为了使 Flarum 的代码保持整洁和一致，我们有需要遵循一套代码风格。如果您对此有疑问，请阅读相关源代码。

也不要担心自己写的不完美，StyleCI 和 Prettier 会自动为每一个拉取请求美化代码。所以，再也不怕被格式烦到了。

PHP#

Flarum 遵循 PSR-2 编码规范和 PSR-4 自动加载规范。此外，我们还遵守着 其他风格规范，使用 PHP 7 类型提示和返回类型声明，使用 PHPDoc 提供内联文档。您可以试着模仿他人代码的风格。

  • 命名空间应当是单数（例如：Flarum\Discussion，而非 Flarum\Discussions）
  • 接口命名应当以 Interface 结尾（例如：MailableInterface）
  • 抽象类命名应当以 Abstract 开头（例如：AbstractModel）
  • Trait 命名应当以 Trait 结尾（例如：ScopeVisibilityTrait）

JavaScript#

Flarum 的 JavaScript 代码大多遵循 爱彼迎风格指南。我们使用 ESDoc 提供内联文档。

数据库#

列 的命名应当根据数据类型而定：

  • 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）

表 的命名应当遵循以下规则：

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

CSS#

Flarum 的 CSS 类命名遵循 SUIT CSS 规范，格式为 .组件名-后代名--修饰名。

翻译#

We use a standard key format to name translation keys descriptively and consistently. 我们使用 标准键名格式 来命名翻译键，确保它的一致性和准确性。

贡献者许可协议#

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

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

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

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