Contributing to Discourse development

文档 贡献
1

:bookmark: 本指南专为希望为 Discourse 开源项目做出贡献的人员设计，详细介绍了有效的协作所需的设置和约定。

:person_raising_hand: 所需用户级别：虽然任何人都可以贡献代码，但您需要熟悉 Ruby 和 JavaScript。

摘要

本文档将涵盖以下内容：

  • 设置您的开发环境
  • 了解从何处开始贡献
  • 创建和使用 Discourse 插件
  • 为 Discourse 核心做贡献
  • 遵循的编码约定
  • 在 GitHub 上提交您的贡献

设置开发环境

在开始贡献之前，请确保您的开发环境已正确设置。请按照适用于您平台的指南操作：

了解从何处开始

Discourse 是一个大型项目，了解其底层技术（如 Ruby 和 JavaScript）至关重要。有关如何开始的指导，请参阅新手指南。

创建和使用插件

插件提供了一种以可管理的部分来理解 Discourse 内部结构的方式，并允许您轻松开始贡献代码。从以下内容开始：

获取灵感，请在 Feature 和 Plugin > Extras 中探索热门想法。

为 Discourse 核心做贡献

Discourse 核心代码托管在 GitHub 上的核心仓库中。

签署 CLA

在贡献之前，请阅读并签署电子论坛贡献许可协议。如果没有签署 CLA，团队在法律上不能接受用户的拉取请求 (PR)。

通过入门任务热身

探索 pr-welcome 标签以查找适合开始的任务。

处理错误列表

修复按点赞数排序的开放错误列表中的错误。如果您正在处理某个错误，请留下注释——如果您没有完成，请留下任何相关注释供他人继续您的工作。

帮助处理功能主题

向功能请求提供详细信息和模型图，以帮助其审批过程。请记住，并非所有功能都会包含在核心中。

提高性能

我们欢迎旨在提高客户端或服务器端性能的拉取请求，重点关注高影响力的领域，例如主页或主题视图的初始加载。

改进 Discourse 维护的项目

为 Discourse 维护的其他开源项目做出贡献。一些值得注意的项目包括：

编码约定

命名至关重要

力求网站上使用的术语与数据库中的类和列名（例如“posts”）实现 100% 的一致性。

与最新依赖版本兼容至关重要

确保与 Rails、Ruby 和 Ember 等库的最新稳定版本兼容。更新依赖项时，请测试是否存在回归。

仅测试的贡献是受欢迎的

欢迎仅进行测试的贡献，特别是针对未经测试的过程和控制器操作。除非绝对必要，否则避免使用模拟 (mocking)。

仅重构的贡献不受欢迎

避免提交仅重构的拉取请求。相反，在修复错误或实现功能的同时改进代码。

在 GitHub 上提交代码

分步工作流程

  1. 克隆 Discourse 仓库：

    git clone git@github.com:discourse/discourse.git

  2. 创建一个新分支：

    cd discourse
git checkout -b new_discourse_branch

  3. 编码：

    • 遵守您在代码中找到的现有代码约定。
    • 包含测试并确保它们通过。
    • 引用 Discourse meta 论坛上的相关讨论。

  4. 遵循编码约定：

    • 两个空格，不要使用制表符
    • 没有尾随空格，空行不应有空格
    • 在运算符周围、逗号后、冒号、分号周围、{ 周围和 } 之前使用空格
    • (、[ 之后或 ]、) 之前没有空格
    • 使用 Ruby 1.9 哈希语法：优先使用 { a: 1 } 而不是 { :a => 1 }
    • 类方法优先使用 class << self; def method; end 而不是 def self.method
    • 单行代码块优先使用 { ... } 而不是 do ... end，多行代码块避免使用 { ... }
    • 除非需要，否则避免使用 return

  5. 提交：

    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 安装我们的 pre-commit git 钩子。这将在您每次在 Discourse 核心中提交时自动运行，并在您推送之前在各种语言和模板中发现问题，从而避免等待 GitHub CI 运行。在您的项目根目录中运行：
      mkdir .git/hooks
npx lefthook install

  6. 更新您的分支：

    git fetch origin
git rebase origin/main

  7. Fork：

    git remote add mine git@github.com:<your-username>/discourse.git

  8. 推送到您的远程仓库：

    git push mine new_discourse_branch

  9. 发出 拉取请求：

    • 导航到 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
  1. 回应反馈：
    • 对反馈保持积极响应，并准备好实施建议的更改。
    • 请记住，收到反馈意味着您的工作受到重视并有望被纳入。

感谢您为 Discourse 开源项目做出贡献！

73 个赞