本指南旨在为希望参与 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 和 #plugin: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 性能测试套件
编码约定
命名至关重要
力求网站上使用的术语与数据库中的类和列名称保持 100% 一致（例如，“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
-
提交 (Commit)：
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安装我们的 pre-commit 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”。
在提交拉取请求之前，请清理历史记录，检查你的提交并将小的更改和修复合并到相应的提交中。你可以使用交互式变基命令压缩提交：
git fetch origin
git checkout new_discourse_branch
git rebase origin/main
git rebase -i
< 编辑器打开并允许你更改提交历史 >
< 遵循编辑器底部的说明 >
git push -f mine new_discourse_branch
- 回应反馈：
- 积极回应反馈，并准备好实施建议的更改。
- 请记住，反馈意味着你的工作受到重视，并计划将其纳入。
感谢你为 Discourse 开源项目做出的贡献！