本指南专为希望为 Discourse 开源项目做出贡献的开发者设计，详细介绍了有效协作所需的设置和约定。
所需用户等级：虽然任何人都可以提交代码，但您需要熟悉 Ruby 和 JavaScript。
摘要
本文档将涵盖以下内容：
- 设置您的开发环境
- 了解从哪里开始贡献
- 创建和使用 Discourse 插件
- 为 Discourse 核心代码做出贡献
- 需要遵循的编码规范
- 在 GitHub 上提交您的贡献
设置开发环境
在开始贡献之前，请确保您的开发环境已正确设置。请按照适合您平台的指南操作：
- 所有平台：使用 Docker 安装 Discourse 用于开发
- Mac OS X：在 macOS 上安装 Discourse 用于开发的初学者指南
- Linux (Ubuntu)：在 Ubuntu 上安装 Discourse 用于开发的初学者指南
- Windows：在 Windows 10 上安装 Discourse 用于开发的初学者指南
了解从哪里开始
Discourse 是一个大型项目，了解其底层技术（如 Ruby 和 JavaScript）至关重要。有关如何开始的指导，请参阅 新手指南。
创建和使用插件
插件提供了一种以可管理的部分了解 Discourse 内部机制的方式，并让您能够轻松开始贡献代码。从以下资源开始：
- Developing Discourse Plugins - Part 1 - Create a basic plugin
- (deprecated) Plugin outlet locations theme component
如需灵感，请在 Contribute > Feature 和 Customization > Extras 中探索热门想法。
为 Discourse 核心代码做出贡献
Discourse 核心代码在 GitHub 上的核心仓库 中进行管理。
签署 CLA
在贡献之前，请阅读并签署 电子 Discourse 论坛贡献许可协议。团队无法合法接受未签署 CLA 的用户提交的拉取请求（PR）。
通过入门任务热身
探索 pr-welcome 标签以找到适合开始的任务。
处理缺陷列表
修复 按点赞数排序的开放缺陷列表 中的缺陷。如果您正在处理某个缺陷，请留下备注——如果您无法完成，请留下任何相关说明，以便他人继续您的工作。
协助功能主题
为 功能请求 提供详细信息和原型，以协助其审批流程。请记住，并非每个功能都会被纳入核心。
提升性能
我们欢迎能够提升客户端或服务器端性能的拉取请求，重点关注高影响区域，如首页或主题视图的初始加载。
改进 Discourse 维护的项目
为 Discourse 维护的其他开源项目做出贡献。一些值得注意的项目包括：
- Logster - Web GUI 日志查看器
- Message Bus - 实时站点交互引擎
- Rack Mini Profiler - 诊断工具
- Discourse API - API 客户端
- Discourse Docker - Discourse 分发引擎
- WP Discourse - WordPress 插件
- Memory Profiler - Ruby 性能分析器
- Ember Performance - Ember 性能测试套件
编码规范
命名至关重要
力求站点上使用的术语与数据库中类和列的名称（例如，「posts」）完全一致。
与最新依赖版本兼容至关重要
确保与 Rails、Ruby 和 Ember 等库的最新稳定版本兼容。更新依赖时请测试是否有回归问题。
欢迎仅包含测试的贡献
欢迎测试贡献，特别是针对未测试的流程和控制器操作。除非绝对必要，否则避免使用模拟（mocking）。
不欢迎仅重构的贡献
避免提交仅重构的拉取请求。相反，请在修复缺陷或实现功能的同时改进代码。
在 GitHub 上提交代码
分步工作流程
-
克隆 Discourse 仓库：
git clone https://github.com/discourse/discourse.git -
创建新分支：
cd discourse git checkout -b new_discourse_branch -
编写代码：
- 遵守代码中现有的编码规范。
- 包含测试并确保它们通过。
- 引用 Discourse 元论坛 上的相关讨论。
-
遵循编码规范：
- 使用两个空格，不使用制表符
- 行尾不留空格，空行不应包含空格
- 在运算符周围、逗号后、冒号后、分号后、
{周围和}之前使用空格 (、[之后或]、)之前不留空格- 使用 Ruby 1.9 哈希语法：优先使用
{ a: 1 }而非{ :a => 1 } - 类方法优先使用
class << self; def method; end而非def self.method - 单行代码块优先使用
{ ... }而非do ... end，多行代码块避免使用{ ... } - 非必要时避免使用
return
-
提交：
git commit -m "变更的简短摘要" -m "变更的详细描述"切勿留空提交信息——这是一份有用的指南，用于编写提交信息。信息应以简短（最多 72 个字符）的摘要开头，后跟一个空行，然后是更详细的变更描述。如有需要，可使用 Markdown 语法进行简单样式设置。
请确保根据 Discourse 约定 为提交标题添加前缀。
5 (a). 代码检查：
JavaScript 代码使用 eslint 进行检查，并使用 prettier 格式化。Ruby 使用 RuboCop 进行检查，并使用 Syntax Tree 格式化。SCSS/CSS 使用 stylelint 进行检查。Ember 模板使用 ember-template-lint 进行检查。当您为 Discourse 创建拉取请求时，所有这些检查都会在 GitHub Actions 中自动运行。- 强烈建议您使用
lefthook安装我们的预提交 Git 钩子。这将在您提交 Discourse 核心代码时自动运行，并在您将代码推送到 GitHub 并等待 GitHub CI 运行之前，针对各种语言和模板提出问题。请在项目根目录运行以下命令：pnpm lefthook install
- 强烈建议您使用
-
更新您的分支：
git fetch origin git rebase origin/main -
派生（Fork）：
git remote add mine git@github.com:<your-username>/discourse.git -
推送到您的远程仓库：
git push mine new_discourse_branch -
发起 拉取请求：
- 导航到 GitHub 上的您的仓库。
- 点击「Pull Request」。
- 在分支字段中输入您的分支名称。
- 点击「Update Commit Range」。
- 在「Commits」和「Files Changed」选项卡中验证更改。
- 提供标题和描述。
- 点击「Send pull request」。
在提交拉取请求之前，请清理历史记录，检查您的提交，并将微小的更改和修复压缩到相应的提交中。您可以使用交互式变基命令压缩提交：
git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i
< 编辑器打开并允许您更改提交历史 >
< 遵循编辑器底部的说明 >
git push -f mine new_discourse_branch
- 回应反馈：
- 积极回应反馈，并准备好实施建议的更改。
- 请记住，收到反馈意味着您的工作受到重视并有望被纳入。
感谢您为 Discourse 开源项目做出贡献！