发布新版本

本指南面向维护者。 这些特别的人拥有一个或多个 Jekyll 仓库的 写入权限（write access），并负责帮助审核与合并其他人的贡献。你可能会觉得这里的内容很有趣，但它显然并不适合所有人。

在发布版本之前，最重要的一件事是：不要紧张。

大多数操作都可以回退，即使你真的发布了一个不完整的 gem 版本，我们也完全可以跳过那个版本继续后续发布。

如果你感到不确定，或者不知道下一步该做什么，请不要犹豫，直接联系其他维护者。

更新版本

唯一需要你手动修改版本号的重要位置，是 lib/jekyll/version.rb。

只要修改这里，其它地方通常都会自动正常工作。

版本号通常采用 "major.minor.patch" 格式。

有时我们也会发布预发布版本（pre-release），格式通常为：

```text id=”0ew8z8” “major.minor.patch.suffix”


其中 `suffix` 并没有统一标准，可以是：

* `pre.alpha1`
* `pre.rc2`
* `beta3`

等等。

在确定正确版本号之前，请先查看历史文档 `History.markdown` 中的 `## HEAD` 部分。

* 如果存在 `Major Enhancements` 子章节

  * 增加版本号中的 `major`

  * 同时将 `minor` 与 `patch` 重置为 `0`

  * 如有需要可添加 `suffix`

  * 例如：

    ```text id="44n4ul"
    "3.9.1" => "4.0.0"
    ```

    或：

    ```text id="7g2c7o"
    "3.9.1" => "4.0.0.alpha1"
    ```

  * 然后继续发布流程的下一步

* 如果存在 `Minor Enhancements` 子章节

  * 仅增加 `minor`

  * 并将 `patch` 重置为 `0`

  * 如有需要可添加 `suffix`

  * 例如：

    ```text id="2g4cje"
    "4.0.2" => "4.1.0"
    ```

    或：

    ```text id="19y6b8"
    "4.1.0" => "4.2.0.pre"
    ```

  * 然后继续下一步

* 其它情况

  * 仅增加 `patch` 或 `suffix`
  * 例如：

    ```text id="1gprz6"
    "4.0.2" => "4.0.3"
    ```

    或：

    ```text id="njlwmk"
    "4.1.0.beta3" => "4.1.0.rc"
    ```

### 撰写发布帖子
{: #write-a-release-post}

如果之前还没有创建发布文章（release post），你可以使用内置的 `rake` 命令快速生成：

```sh id="40mb4h"
bundle exec rake site:releases:new[3.8.0]

其中 3.8.0 需要替换为新的版本号。

然后编写发布文章。

请务必感谢自上一个版本发布以来参与贡献的所有协作者与维护者。

你可以使用以下命令生成贡献者列表：

```sh id=”xq0a6s” git shortlog -sn master…v3.7.2


其中 `v3.7.2` 是上一个版本对应的 Git 标签。

如果本地不存在该标签，请先执行：

```sh id="k7jtb5"
git pull

发布文章完成后，请记得提交 Pull Request。

更新“历史”文档

将 History.markdown 中的第一个标题替换为正式版本信息，例如：

```diff id=”lmz1jp”

修改版本号与日期。

新的 ## HEAD 标题会在下次 Pull Request 合并时自动重新生成。

然后，根据优先级重新整理各个子章节，顺序如下：

```text id=”mjlwm7”

4.2.0 / 2020-12-14

Major Enhancements

…

Minor Enhancements

…

Bug Fixes

…

Security Fixes

…

Optimization Fixes

…

Development Fixes

…

Site Enhancements

…


完成后，运行以下命令更新网站：

```sh id="1itcqt"
bundle exec rake site:generate

该命令会：

建议你再手动检查一次 History.markdown，看看是否存在拼写错误等问题。

如果发现问题，可以直接手动修复。

在网站 changelog 生成完成后，请提交你的修改。

发布版本

执行此步骤前，请确认以下事项已经完成：

然后：

```text id=”mdplgo” “Release :gem: v[CURRENT_VERSION]”


现在剩下的唯一操作就是：

```sh id="jlwmf8"
git push upstream master

其中 upstream 指向：

```text id=”90q2gk” git@github.com:jekyll/jekyll.git


这会触发 GitHub Actions 工作流，并自动执行：

* 构建新的 gem
* 为发布提交创建 tag
* 推送 tag 到 GitHub
* 最终将新 gem 发布到 RubyGems

你也不需要手动创建 GitHub Release。

当发布工作流推送新 tag 后，@jekyllbot 会自动完成 GitHub Release 创建。

如果工作流成功完成，那么发布流程就结束了！ :tada:

现在可以庆祝一下了！

如果你拥有 [@jekyllrb](https://twitter.com/jekyllrb) Twitter 账号权限，记得在那里发布此次版本更新消息。

如果没有权限，可以让其他维护者帮忙发布，或者申请权限。

### 生成文档
{: #build-the-docs}

我们会将文档打包成一个 :gem: Gem，方便离线使用。

这部分工作由 [**jekyll-docs**](https://github.com/jekyll/jekyll-docs#building) 仓库完成，那里也提供了更详细的说明。

## 对于非核心 gem
{: #for-non-core-gems}

如果你并不是 `jekyll/jekyll` 的维护者，那么整个发布流程会简单很多。

通常流程如下：

* 手动更新 gem 版本号（一般位于 `lib/<plugin_name>/version.rb`）

* 更新历史记录文件

* 提交修改到默认分支，推荐提交信息：

  ```text id="l33h2s"
  "Release :gem: v[CURRENT_VERSION]"

如果你不确定具体流程，请务必询问项目维护者！