改进此页面

贡献

嗨！有兴趣为 Jekyll 做贡献吗？我们非常欢迎你的帮助。Jekyll 是一个开源项目，由像你这样的用户一次一个贡献构建而成。

在哪里获得帮助或报告问题

请参阅 支持指南

贡献方式

无论你是开发人员、设计师还是 Jekyll 爱好者，都有很多方式可以做出贡献。以下是一些想法

  • 在你的电脑上安装 Jekyll 并试用一下。它能正常工作吗？它能达到你的预期吗？如果不能，打开一个问题 并告诉我们。
  • 对项目的一些 开放问题 发表评论。你是否遇到过同样的问题？知道解决方法吗？你有什么建议可以改善该功能吗？
  • 通读 文档，每当你看到令人困惑的地方或对可以改进的地方有建议时，请点击“改进此页面”按钮。
  • 浏览 Jekyll 讨论论坛，并回答问题。你很有可能已经经历了其他用户正在经历的事情。
  • 找到一个 开放问题（尤其是 那些标记为 help-wanted 的问题），并提交一个拟议的修复。如果这是你的第一个拉取请求，我们保证不会咬人，并且很乐意回答任何问题。
  • 通过在本地测试更改和查看建议来帮助评估 开放拉取请求。

提交拉取请求

拉取请求一般

  • 建议的更改越小越好。如果你想建议两个不相关的更改，请提交两个请求。

  • 信息越多越好。明智地使用请求主体。描述所做的更改、你为何做出这些更改以及它们对用户的影响。

  • 如果这是你的第一个请求，了解 GitHub 流程 可能会有帮助。

  • 如果你正在提交代码贡献，请务必阅读以下 代码贡献 部分。

通过 github.com 提交请求

许多小更改可以通过 github.com Web 界面完全完成。

  1. 导航到 jekyll/jekyll 中你想要编辑的文件。
  2. 点击右上角的铅笔图标编辑文件
  3. 做出你建议的更改
  4. 点击“建议文件更改”
  5. 点击“创建请求”
  6. 为你的建议更改添加一个描述性标题和详细说明。信息越多越好。
  7. 点击“创建请求”

就是这样！当其他人查看你的建议更改并提供反馈时，你会自动订阅以接收更新。

通过 Git 命令行提交请求

  1. 通过点击 jekyll/jekyll 右上角的“Fork”来 fork 项目。
  2. 在本地克隆存储库 git clone https://github.com/<you-username>/jekyll。
  3. 创建一个新的、描述性名称的分支来包含你的更改（ git checkout -b my-awesome-feature ）。
  4. 黑掉它，添加测试。不一定按此顺序。
  5. 通过运行 script/cibuild 确保一切仍然通过（参见下面的 测试部分）
  6. 推送分支（ git push origin my-awesome-feature ）。
  7. 通过访问 https://github.com/<your-username>/jekyll 并按照屏幕顶部的说明创建请求。

建议更新文档

我们希望 Jekyll 文档尽可能好。我们已经开源了我们的文档，如果你发现它有缺陷，我们欢迎任何请求。

如何提交更改

您可以在 docs 目录中找到 jekyllrb.com 的文档。请参阅上面的 提交拉取请求 部分，了解如何提出更改的信息。

需要注意的是，所有拉取请求都应指向 master 分支（默认分支）。

为 jekyllrb.com 更新 FontAwesome 图标集

我们使用 FontAwesome 的自定义版本，其中仅包含我们使用的图标。

如果您需要使用我们自定义图标集中尚不可用的图标更新我们的文档，则必须使用 Icomoon 的生成器重新生成图标集

  1. 转到 https://icomoon.io/app/。
  2. 单击顶部水平栏上的 导入图标 并上传现有的 <jekyll>/docs/icomoon-selection.json。
  3. 单击页面下方 从库中添加图标..，并添加“Font Awesome”。
  4. 从库中选择所需的图标（确保它是“FontAwesome”库，而不是“IcoMoon-Free”库）。
  5. 单击底部水平栏上的 生成字体。
  6. 检查包含的图标，然后单击 下载 继续。
  7. 提取字体文件，并将 CSS 调整为我们在 Jekyll 中使用的路径
  • 将整个 fonts 目录复制并覆盖 <jekyll>/docs/ 中现有的目录。
  • 复制 selection.json 的内容，并覆盖 <jekyll>/docs/icomoon-selection.json 中现有的内容。
  • 复制整个 @font-face {} 声明，以及仅在下面复制新图标的 css 声明，以更新 <jekyll>/docs/_sass/_font-awesome.scss sass 部分。
  • 通过在 fonts/FontAwesome.* 之前添加 ../ 来修复 @font-face {} 声明中的路径，如下所示：('../fonts/Fontawesome.woff?9h6hxj')。

添加插件

如果您想将您的插件添加到插件列表中，请提交一个拉取请求，修改插件页面源文件，在根据其类型添加指向您插件的链接。

代码贡献

有兴趣提交拉取请求？太棒了。继续阅读。有一些常见的陷阱，我们很乐意帮助您避免。

测试和文档

任何时候您提出代码更改，您还应该在同一个拉取请求中包含对文档和测试的更新。

文档

如果您的贡献改变了任何 Jekyll 行为，请务必更新文档。文档位于docs/_docs文件夹中（剧透提示：这是一个 Jekyll 网站！）。如果文档中缺少信息，请随时添加。出色的文档成就出色的项目。在您的拉取请求中包含对文档的更改，一旦合并，jekyllrb.com将被更新。

测试

  • 如果您正在为现有功能创建小的修复或补丁，一个简单的测试就足够了。您通常可以从tests文件夹中的现有示例中复制/粘贴，但是如果您需要，您可以了解我们的测试套件Shoulda和RSpec-Mocks。

  • 如果这是一个全新的功能，请创建一个新的Cucumber功能，在适当的地方重复使用现有步骤。

一般代码贡献

  • Jekyll 使用Rubocop静态分析器来确保贡献遵循GitHub Ruby 风格指南。请使用script/fmt检查您的代码，并在推送您的分支之前解决任何错误。

  • 不要在您的拉取请求中提升 Gem 版本（如果您不知道这意味着什么，您可能没有这样做）。

  • 您可以使用命令script/console启动一个 REPL 来探索 Jekyll 方法的结果。它还为您提供了快速创建网站或配置的有用方法。随时查看！

  • 以前，我们使用 WIP Probot 应用程序来帮助贡献者确定他们的拉取请求是否已准备好进行审查。请改用草稿拉取请求。当您准备好时，将拉取请求标记为已准备好进行审查

本地运行测试

测试依赖项

要运行测试套件并构建 gem，您需要通过运行以下命令安装 Jekyll 的依赖项

script/bootstrap

在进行任何更改之前，运行测试并确保它们通过（以确认您的环境已正确配置）

script/cibuild

如果您只更新 test/ 中的文件，可以使用以下命令

script/test test/blah_test.rb

如果您只更新 .feature 文件，可以使用以下命令

script/cucumber features/blah.feature

script/test 和 script/cucumber 都可以不带参数运行，以运行其各自的整个套件。

Visual Studio Code 开发容器

如果您已安装 Visual Studio Code 和 远程开发扩展包，那么只需在 Visual Studio Code 中打开此存储库，然后按照提示“在开发容器中重新打开”即可设置并准备好一个已安装所有必需组件的新环境。

感谢

谢谢！破解 Jekyll 应该很有趣。如果您发现其中任何内容难以理解，请告诉我们，以便我们改进我们的流程或文档！