本指南专为希望为 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 - 诊断工具
- 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 论坛元讨论中相关的讨论。
-
遵循编码约定：
- 两个空格，不要使用制表符
- 没有尾随空格，空行不应包含空格
- 在运算符周围、逗号后、冒号、分号后、
{周围以及}前使用空格 (、[后面或]、)前面没有空格- 使用 Ruby 1.9 hash 语法：优先使用
{ 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 进行检查，并使用 Syntax Tree 进行格式化。SCSS/CSS 使用 stylelint 进行检查。Ember 模板使用 ember-template-lint 进行检查。所有这些检查都会在您为 Discourse 创建拉取请求时在 GitHub Actions 中自动运行。- 我们强烈建议您使用
lefthook安装我们的预提交 git 钩子。每次在 Discourse 核心中提交时，它都会自动运行，并在您推送之前在各种语言和模板中发现问题，而无需等待 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”。
在提交拉取请求之前，请清理历史记录，检查您的提交，并将小的更改和修复合并到相应的提交中。您可以使用交互式 rebase 命令合并提交：
git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i
< 编辑器会打开，允许您更改提交历史 >
< 遵循编辑器底部的说明 >
git push -f mine new_discourse_branch
- 响应反馈：
- 对反馈保持响应，并准备好实施建议的更改。
- 请记住，反馈意味着您的工作受到重视并旨在被采纳。
感谢您为 Discourse 开源项目做出的贡献！