贡献代码或文档

你好！有兴趣为 Jekyll 做贡献吗？我们非常欢迎你的加入。

Jekyll 是一个开源项目，它是由像你这样的用户一次次贡献共同构建出来的。

在哪里获取帮助或反馈问题

请查看支持指南

参与贡献的方式

无论你是开发者、设计师，还是单纯热爱 Jekyll 的用户，都有很多方式可以参与贡献。下面是一些建议：

在你的电脑上安装 Jekyll 并亲自体验一下。它运行正常吗？表现是否符合你的预期？如果没有，请创建一个 Issue 告诉我们。
参与项目中的一些公开 Issue 讨论。你是否遇到过相同问题？知道解决办法？或者对功能改进有建议？
阅读文档，每当你发现内容令人困惑，或者觉得某些地方可以改进时，点击 “improve this page” 按钮提交修改。
浏览 Jekyll 讨论论坛，帮助回答其他用户的问题。很有可能，你已经遇到过别人现在正在经历的问题。
找一个公开 Issue（尤其是那些带有 help-wanted 标签的），然后提交修复方案。如果这是你的第一个 Pull Request，我们保证不会“咬人”，也很乐意回答你的问题。
帮助审核公开 Pull Request，例如本地测试修改内容，或者检查提交方案是否合理。

提交 Pull Request

Pull Request 通用建议

提交的改动越小越好。如果你想提交两个互不相关的修改，请拆分成两个 Pull Request。
信息越详细越好。请合理利用 Pull Request 描述区域，说明：
- 修改了什么
- 为什么这样修改
- 会对用户产生什么影响
如果这是你的第一个 Pull Request，建议先了解一下 GitHub Flow。
如果你提交的是代码修改，请务必阅读下面的代码贡献章节。

通过 github.com 提交 Pull Request

很多小修改其实完全可以直接通过 github.com 网页界面完成。

打开你想修改的 jekyll/jekyll 文件
点击右上角的铅笔图标编辑文件
进行修改
点击 “Propose file change”
点击 “Create pull request”
为你的修改添加清晰标题与详细说明，信息越多越好
点击 “Create pull request”

就这样！

之后，当其他人审核你的修改并提供反馈时，你会自动收到通知。

通过 Git 命令行提交 Pull Request

在 jekyll/jekyll 页面右上角点击 “Fork” 复制项目
本地克隆仓库：

```sh id=”5jqq4i” git clone https://github.com//jekyll

3. 创建一个新的描述性分支用于开发：

```sh id="mjlwmv"
git checkout -b my-awesome-feature

开始修改代码并添加测试（顺序不限）
运行以下命令确保全部测试通过（详见下方本地运行测试章节）：

```sh id=”v2g2mk” script/cibuild

6. 推送分支：

```sh id="5rk3fk"
git push origin my-awesome-feature

访问：

```text id=”qolw5r” https://github.com//jekyll

并根据页面顶部提示创建 Pull Request。

## 提交文档更新
{: #proposing-updates-to-the-documentation}

我们希望 Jekyll 文档尽可能完善。

文档同样已经开源，因此如果你发现内容不足，非常欢迎提交 Pull Request。

### 如何提交文档修改
{: #how-to-submit-changes}

jekyllrb.com 的文档位于 [docs](https://github.com/jekyll/jekyll/tree/master/docs) 目录中。

关于如何提交修改，请参考上方的[提交 Pull Request](#submitting-a-pull-request)章节。

有一个容易踩坑的地方：

所有 Pull Request 都应该提交到 `master` 分支（默认分支）。

### 更新 jekyllrb.com 的 FontAwesome 图标集
{: #updating-fontawesome-iconset-for-jekyllrb-com}

我们使用的是一个自定义精简版 FontAwesome，仅包含当前使用到的图标。

如果你需要添加当前图标集中不存在的新图标，需要使用 Icomoon Generator 重新生成图标集：

1. 打开 [https://icomoon.io/app/](https://icomoon.io/app/)
2. 点击顶部工具栏中的 `Import Icons`，上传现有的 `<jekyll>/docs/icomoon-selection.json`
3. 点击页面下方的 `Add Icons from Library..`，添加 “Font Awesome”
4. 从图标库中选择需要的新图标（注意选择 “FontAwesome” 而不是 “IcoMoon-Free”）
5. 点击底部工具栏中的 `Generate Font`
6. 检查图标后点击 `Download`
7. 解压字体文件，并按以下方式适配 Jekyll 使用的 CSS 路径：

* 将整个 `fonts` 目录复制到 `<jekyll>/docs/` 并覆盖原文件
* 将 `selection.json` 内容复制到 `<jekyll>/docs/icomoon-selection.json`
* 将整个 `@font-face {}` 声明以及下方 **新增图标的 CSS 声明** 复制到：

```text id="34mjlwm"
<jekyll>/docs/_sass/_font-awesome.scss

修改 @font-face {} 中的路径，在 fonts/FontAwesome.* 前增加 ../：

```text id=”3x8y3x” (‘../fonts/Fontawesome.woff?9h6hxj’)

### 添加插件
{: #adding-plugins}

如果你希望将自己的插件添加到[插件列表](https://jekyllrb.com/docs/plugins/#available-plugins)中，请提交 Pull Request 修改[插件页面源码](https://github.com/jekyll/jekyll/blob/master/docs/_docs/plugins.md)。

根据插件类型，将插件链接添加到对应分类下即可。

## 代码贡献
{: #code-contributions}

想提交 Pull Request？太好了。

继续阅读，下面有一些常见坑点，希望能帮助你避免踩坑。

### 测试与文档
{: #tests-and-documentation}

每次提交代码修改时，你都应该同时更新：

* 文档
* 测试

并一起包含在同一个 Pull Request 中。

#### 文档
{: #documentation}

如果你的修改影响了 Jekyll 的行为，请务必同步更新文档。

文档位于 `docs/_docs` 目录中（没错，它本身也是一个 Jekyll 网站 😄）。

如果你发现文档缺少内容，也欢迎直接补充。

优秀的文档能够成就优秀的项目。

请将文档修改与代码一起提交到 Pull Request 中，合并后 `jekyllrb.com` 会自动更新。

#### 测试
{: #tests}

* 如果你只是修复一个小 Bug 或小功能，一个简单测试通常已经足够。

  你通常可以直接参考 `tests` 目录中的现有示例。

  如果需要，可以了解我们的测试框架：

  * [Shoulda](https://github.com/thoughtbot/shoulda/tree/master)
  * [RSpec-Mocks](https://github.com/rspec/rspec-mocks)

* 如果是全新功能，请新增一个 [Cucumber](https://github.com/cucumber/cucumber/) feature，并尽量复用已有步骤。

### 代码贡献通用建议
{: #code-contributions-generally}

* Jekyll 使用 [Rubocop](https://github.com/bbatsov/rubocop) 静态分析工具，确保代码符合 [GitHub Ruby Styleguide](https://github.com/styleguide/ruby)。

  请在推送代码前运行：

```sh id="1l7jlwm"
script/fmt

并修复所有错误。

不要在 Pull Request 中修改 Gem 版本号（如果你不知道这是什么意思，那你大概率也不需要修改）。
你可以使用：

```sh id=”y2oj3p” script/console

启动 REPL 环境，用于探索 Jekyll 方法执行结果。

它还提供了很多便捷方法，可快速创建站点与配置。

[欢迎体验！](https://github.com/jekyll/jekyll/blob/master/script/console)

* 过去我们使用 WIP Probot 帮助贡献者标记 Pull Request 是否已准备好审核。

  现在请改用 [draft pull request](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests)。

  当你准备好后，可以：

  [将 Pull Request 标记为 ready for review](https://help.github.com/en/articles/changing-the-stage-of-a-pull-request)

## 本地运行测试
{: #running-tests-locally}

### 测试依赖
{: #test-dependencies}

要运行测试套件并构建 gem，需要先安装 Jekyll 依赖：

```sh id="mjlwm0"
script/bootstrap

在开始修改前，请先运行测试并确认通过（确保环境配置正确）：

```sh id=”wjvll2” script/cibuild

如果你只修改了 `test/` 中的某个文件，可以使用：

```sh id="3w5w35"
script/test test/blah_test.rb

如果你只修改了 .feature 文件，可以使用：

```sh id=”3xw3xw” script/cucumber features/blah.feature

`script/test` 与 `script/cucumber` 都可以不带参数执行，以运行完整测试套件。

## Visual Studio Code 开发容器
{: #visual-studio-code-development-container}

如果你安装了：

* [Visual Studio Code](https://code.visualstudio.com/)
* [Remote Development Extension Pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack)

那么只需在 VS Code 中打开该仓库，并按照提示选择：

```text id="4f4f4f"
Re-open In A Development Container

即可自动创建一个全新开发环境，并安装所有所需依赖。

感谢

感谢你！

参与 Jekyll 开发本应是一件有趣的事情。

如果你觉得某些流程难以理解，请告诉我们，这样我们就可以继续改进流程与文档。