本指南旨在为希望为 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
为了获得灵感，请在 Feature 和 Plugin > Extras 中探索热门想法。
为 Discourse 核心做贡献
Discourse 核心代码托管在 GitHub 上的核心仓库中。
签署 CLA
在贡献之前，请阅读并签署电子论坛贡献许可协议。如果没有签署 CLA，团队在法律上不能接受用户的拉取请求 (PR)。
从入门任务热身
探索 pr-welcome 标签以查找适合开始的任务。
处理错误列表
修复按点赞数排序的开放错误列表中的错误。如果您正在处理一个错误，请留下注释——如果您没有完成它，请留下任何相关的注释供其他人继续您的工作。
协助功能主题
向功能请求提供详细信息和模型图，以帮助其审批过程。请记住，并非所有功能都会包含在核心中。
提高性能
我们欢迎提高客户端或服务器端性能的拉取请求，重点关注高影响力的领域，例如主页或主题视图的初始加载。
改进 Discourse 维护的项目
为 Discourse 维护的其他开源项目做出贡献。一些值得注意的项目包括：
- Logster - Web GUI 日志查看器
- Message Bus - 实时站点交互引擎
- Rack Mini Profiler - 诊断工具
- Onebox - 用于 URL 预览的 Ruby gem
- Discourse API - API 消费者
- Discourse Docker - Discourse 分发引擎
- WP Discourse - WordPress 插件
- Memory Profiler - Ruby 分析器
- Ember Performance - Ember 性能测试套件
编码约定
命名至关重要
力求网站上使用的术语与数据库中的类和列的名称（例如，“posts”）实现 100% 的一致性。
与最新依赖版本兼容至关重要
确保与 Rails、Ruby 和 Ember 等库的最新稳定版本兼容。更新依赖项时，请测试回归。
仅测试的贡献是受欢迎的
欢迎测试贡献，特别是针对未经测试的过程和控制器操作。除非绝对必要，否则避免使用模拟。
仅重构的贡献不受欢迎
避免提交仅重构的拉取请求。相反，在修复错误或实现功能的同时改进代码。
在 GitHub 上提交代码
分步工作流程
-
克隆 Discourse 仓库：
git clone https://github.com/discourse/discourse.git -
创建一个新分支：
cd discourse git checkout -b new_discourse_branch -
编码：
- 遵守您在代码中找到的现有代码约定。
- 包含测试并确保它们通过。
- 引用 Discourse meta 论坛上的相关讨论。
-
遵循编码约定：
- 两个空格，不使用制表符
- 没有尾随空格，空行不应包含空格
- 在运算符、逗号、冒号、分号周围，在
{周围以及在}之前使用空格 (、[之后或]、)之前没有空格- 使用 Ruby 1.9 哈希语法：倾向于
{ a: 1 }而不是{ :a => 1 } - 倾向于使用
class << self; def method; end而不是def self.method来定义类方法 - 单行代码块倾向于使用
{ ... }而不是do ... end，多行代码块避免使用{ ... } - 除非需要，否则避免使用
return
-
提交：
git commit -m "A short summary of the change" -m "A detailed description of the change"切勿留空提交信息 - 这是一个有用的指南，用于编写提交信息。消息的第一行应包含一个简短的（最多 72 个字符）摘要，后跟一个空行，然后是更改的详细描述。如果需要，您可以使用 markdown 语法进行简单样式设置。
确保根据Discourse 约定为提交标题添加前缀。
5 (a)。 代码检查 (Linting)：
JavaScript 代码使用 eslint 和 prettier 的格式化条件进行检查。Ruby 使用 RuboCop 进行检查。所有这些检查都会在您向 Discourse 创建拉取请求时在 GitHub Actions 中自动运行。- 我们强烈建议您使用
lefthook安装我们的预提交 git 钩子。这将在您每次在 Discourse 核心中进行提交时自动运行，并在您推送之前就发现各种语言和模板存在的问题，从而避免等待 GitHub CI 运行。在您的项目根目录中运行此命令：mkdir .git/hooks npx 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”。
在提交拉取请求之前，清理历史记录，回顾您的提交，并将小的更改和修复合并到相应的提交中。您可以使用交互式 rebase 命令来合并提交：
git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i
< 编辑器打开，允许您更改提交历史 >
< 遵循编辑器底部的说明 >
git push -f mine new_discourse_branch
- 回应反馈：
- 对反馈保持响应，并准备好实施建议的更改。
- 请记住，反馈意味着您的工作受到重视并旨在被采纳。
感谢您为 Discourse 开源项目做出贡献！
