第14章 参与构建 Flarum：开发者指南与贡献流程

Version: 2.x 参与构建 Flarum 想为 Flarum 的开发做出贡献吗？太棒了！无论是提交 Bug 报告还是发起 Pull Request，每一份贡献都备受珍视和欢迎。没有社区的无私奉献，Flarum 就不可能存在。 在参与贡献之前，请务必阅读行为准则。 本文档是为希望向 Flarum 贡献代码的开发者编写的指南。如果你是初学者，建议先阅读扩展文档中的“入门指南”，以便更深入地了解 Flarum 的工作原理。 为何参与 Flarum 贡献？ ⚡ 产生实际影响。全球有数千个 Flarum 实例，汇聚了数百万最终用户。参与 Flarum 开发，你的代码将对所有这些实例产生积极影响。 🔮 塑造 Flarum 的未来。我们的待办事项清单很长，但开发时间有限。如果你愿意牵头推进某个功能或变更，它落地的可能性会大得多，你也能将自己的愿景付诸实践。此外，我们的路线图和里程碑由核心开发团队制定，而我们每个人最初也是贡献者。施加影响的最佳途径就是参与贡献。 🧑‍💻 成为更优秀的工程师。我们的代码库很现代化，我们非常重视良好的工程实践和整洁的代码。同时，在设计、基础设施、性能和扩展性方面还有许多有趣且具挑战性的问题等待解决。特别是对于学生或职业生涯早期的人，参与 Flarum 开发是提升开发技能的绝佳机会。 🎠 这很有趣！我们真正享受在 Flarum 上的工作：这里有大量有趣的挑战和令人愉悦的功能待构建。我们还在论坛和 Discord 服务器上拥有一个活跃的社区。 该做什么？ 查看我们即将发布的里程碑，以了解需要完成的工作。带有“Good first issue”标签的问题列表包含了一些相对容易上手的项目。如果有什么不确定的，请随时提问！我们曾经也是新手。 如果你计划着手处理某个事项，请先在相关 issue 下评论，或先创建一个新 issue。这样可以确保你的辛勤付出不会白费。 由于 Flarum 高度依赖扩展，我们在开发核心代码及内置扩展时，强烈建议参考我们的扩展文档。建议先从入门介绍开始，以便更好地理解我们的扩展理念。 开发环境搭建 搭建本地代码库 flarum/flarum 是一个“骨架”应用，它通过 Composer 下载核心包和一系列扩展。Flarum 核心、扩展以及上述所用所有包的源代码位于 Flarum 单体仓库 flarum/framework 中。为了对这些部分做出贡献，你需要在本地 fork 并克隆该单体仓库，然后将其作为 Composer 路径仓库添加到你的开发环境中： git clone https://github.com/flarum/flarum.git
cd flarum

# 或者，如果你想直接克隆到当前目录
git clone https://github.com/flarum/flarum.git .
# 注意，目录必须为空

# 为 Flarum monorepo 包设置 Composer 路径仓库
composer config repositories.0 path "PATH_TO_MONOREPO/*/*"
git clone https://github.com//framework.git PATH_TO_MONOREPO
接下来，在 composer.json 中把 minimum-stability 设置为 dev，让 Composer 接受来自本地副本的不稳定版本。 最后运行 composer install，即可从路径仓库完成安装。 本地安装配置好之后，记得在 config.php 中开启 debug 模式，并在 PHP 配置里把 display_errors 设为 On，这样就能看到 Flarum 和 PHP 的错误详情。开启调试模式后，Flarum 的资源文件会在每次请求时强制重新编译，就不用在每次修改扩展的 JavaScript 或 CSS 后都执行 php flarum cache:clear 了。 Flarum 的前端代码使用 ES6 编写，再转译为 JavaScript。开发时需要用 Node.js 和 yarn 重新编译 JavaScript。提交 PR 时请不要把生成的 dist 文件一并提交；改动合并进主分支时会自动处理这些文件。 要参与前端开发，先安装 JavaScript 依赖。monorepo 使用 yarn workspaces，可以方便地一次性安装所有包的 JS 依赖。 cd packages/framework
yarn install
然后就可以在开发过程中监听 JavaScript 文件的变化了： cd framework/core/js
yarn dev
扩展的操作流程也一样。 cd extensions/tags/js
yarn dev
开发工具 分叉并克隆好你即将开发的仓库后，你需要配置本地托管环境，以便测试代码改动。 Flarum 目前不附带开发服务器，因此你需要配置 Apache、NGINX、Caddy 等 Web 服务器来提供本地 Flarum 站点服务。 或者，你也可以使用 Laravel Valet（macOS）、XAMPP（Windows）或 Docker-Flarum（Linux）等工具来托管本地论坛。 大多数 Flarum 贡献者使用 PhpStorm 或 Visual Studio Code 进行开发。 开发流程 典型的贡献流程如下： 🧭 规划贡献 确定要处理的 Issue 搭建开发环境 🌳 从对应分支切出新功能分支。 Bug 修复应提交至最新的稳定分支。 与当前 Flarum 版本完全向后兼容的小功能也可提交至最新稳定分支。 重大功能必须提交至 main 分支，该分支包含即将发布的 Flarum 版本。 内部我们使用 `/` 的命名规范（如 tz/refactor-frontend）。 🔨 编写代码。 编码风格见下文。 🚦 测试代码。 修复 Bug 或添加功能时，按需添加单元测试。 在相关包目录下运行 `vendor/bin/phpunit` 执行测试套件。 关于 Flarum 测试的更多信息见此处。 💾 提交代码并附带说明性提交信息。 如果该改动解决了现有的 Issue（通常应该如此），请在新的一行中包含 "Fixes #123"，其中 123 为 Issue 编号。 遵循 Conventional Commits 规范。 Fix 提交应描述解决了什么问题，而不是修复方法。 🎁 在 GitHub 上提交 Pull Request。 填写 Pull Request 模板。 如果改动涉及视觉呈现，请附上截图或 GIF 展示变化。 切勿将 JavaScript dist 文件提交入库，合并时会自动编译。 🤝 与 Flarum 团队沟通，获得批准。 团队成员将审查代码。我们可能会建议一些修改、改进或替代方案，但对于小型改动，Pull Request 通常能较快被接受。 处理反馈时，请推送新的 commit，不要覆盖或压缩提交（合并时我们会自动 squash）。 🕺 像刚刚为 Flarum 做出贡献一样尽情舞动。 编码风格 为了保持 Flarum 代码库的整洁与一致，我们遵循若干编码风格规范。如有疑问，请直接阅读源码。 不要担心代码风格不完美！StyleCI 和 Prettier 会自动检查每个 Pull Request 的格式，让我们能专注于贡献内容本身，而非代码风格。 PHP Flarum 遵循 PSR-2 编码标准和 PSR-4 自动加载标准。此外，我们还遵守一些其他风格规则。尽可能使用 PHP 7 类型提示和返回类型声明，并使用 PHPDoc 提供内联文档。在贡献中，请尽量模仿代码库中现有的风格。 - 命名空间应为单数（如 `Flarum\Discussion`，而非 `Flarum\Discussions`） - 接口应以 `Interface` 为后缀（如 `MailableInterface`） - 抽象类应以 `Abstract` 为前缀（如 `AbstractModel`） - Trait 应以 `Trait` 为后缀（如 `ScopeVisibilityTrait`） JavaScript Flarum 的 JavaScript 主要遵循 Airbnb 风格指南。我们使用 ESDoc 提供内联文档。 数据库 列名应根据数据类型命名： - `DATETIME` 或 `TIMESTAMP`：`{verbed}_at`（如 `created_at`、`read_at`）或 `{verbed}_until`（如 `suspended_until`） - 表示计数的 `INT`：`{noun}_count`（如 `comment_count`、`word_count`） - 外键：`{verbed}_{entity}_id`（如 `hidden_user_id`） 主要关系可省略动词（如发帖作者仅使用 `user_id`） - `BOOL`：`is_{adjective}`（如 `is_locked`） 表名命名规则： - 使用复数形式（`discussions`） - 多词表名用下划线分隔（`access_tokens`） - 关系表按字母顺序将两个表的单数名称以下划线连接（如 `discussion_user`） CSS Flarum 的 CSS 类名大致遵循 SUIT CSS 命名规范，格式为 `.ComponentName-descendentName--modifierName`。 翻译 我们使用标准的键格式来为翻译键命名，确保描述性强且一致。 贡献者许可协议 将代码贡献给 Flarum 即表示你授予 Flarum 基金会（Stichting Flarum）一项非排他性、不可撤销、全球范围、免版税、可分许可、可转让的许可，允许其在你的所有相关知识产权（包括版权、专利及其他权利）下，按照任何许可条款（包括但不限于：(a) 如 MIT 许可等开源许可；(b) 二进制、专有或商业许可）使用、复制、制作衍生作品、分发并公开表演或展示该贡献。除本协议授予的许可外，你保留对贡献的所有权利、所有权和权益。 你确认能够授予我们上述权利。你声明你有权授予上述许可。如果你的雇主对你创建的知识产权拥有权利，你声明你已获得该雇主的授权，代表其进行贡献，或者该雇主已放弃其对贡献的上述权利。 你声明该贡献是你原创的作品，且据你所知，无人对与贡献相关的发明或专利提出或有权提出任何权利主张。你还声明你未通过签订协议或其他方式承担任何与本协议条款相冲突的法律义务。 Flarum 基金会承认，除本协议明确说明外，你提供的任何贡献均按“原样”提供，不附带任何形式的明示或暗示保证或条件，包括但不限于对所有权、不侵权、适销性或特定用途适用性的任何保证或条件。