From 36cbca0ece3a2dfb59ba7ed99508cf90ee15b257 Mon Sep 17 00:00:00 2001 From: Ashwin Maroli Date: Fri, 4 Mar 2022 21:36:27 +0530 Subject: [PATCH] Document releasing off `*-stable` branches (#8984) Merge pull request 8984 --- docs/_docs/maintaining/index.md | 1 + .../releasing-off-stable-branches.md | 63 +++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 docs/_docs/maintaining/releasing-off-stable-branches.md diff --git a/docs/_docs/maintaining/index.md b/docs/_docs/maintaining/index.md index 1d517ce4..e7a1b607 100644 --- a/docs/_docs/maintaining/index.md +++ b/docs/_docs/maintaining/index.md @@ -15,6 +15,7 @@ Hello! This is where we document various processes for maintaining Jekyll. Being - [Avoiding burnout](avoiding-burnout/) - [Special Labels](special-labels/) - [Releasing a new version](releasing-a-new-version/) +- [Releasing a new version off `*-stable` branches](releasing-off-stable-branches/) Interested in becoming a maintainer? Here is some documentation for **contributors**: diff --git a/docs/_docs/maintaining/releasing-off-stable-branches.md b/docs/_docs/maintaining/releasing-off-stable-branches.md new file mode 100644 index 00000000..1fa16fa4 --- /dev/null +++ b/docs/_docs/maintaining/releasing-off-stable-branches.md @@ -0,0 +1,63 @@ +--- +title: Releasing off older stable branches +--- + +Apart from having releases cut from the default `master` branch, Jekyll Core may occasionally cut releases containing security patches and +critical bug-fixes for older versions under maintenance. Such releases are cut from specially named branches, following the pattern +`[x].[y]-stable` where `[x]` denotes semver-major-version and `[y]`, the semver-minor-version. For example, the branch `3.9-stable` refers to +commits released as part of `jekyll-3.9.x` series. + +Co-ordinating a release off a `*-stable` branch is complicated mainly because the default branch has to inevitably reflect the release as well. + +## Requirements + +- The maintainer has to have **write-access** to both the concerned `*-stable` and `master` branches. +- The maintainer needs to complete the task using their **local CLI program** instead of dispatching via GitHub Web UI. +- The maintainer is abreast with the workflow to [release off `master`]({{ 'docs/maintaining/releasing-a-new-version/' | relative_url }}). The + procedure documented in the following section is an abridged adaptation of the workflow for `master`. +- A release post has been drafted and **is awaiting publish to `master`** via an approved pull request. +- Stable internet connection. + +## Trigger release workflow + +1. Ensure that you've **checked out the concerned `*-stable` branch** and is up-to-date with its counterpart at `jekyll/jekyll` at GitHub. +2. Bump the `VERSION` string in `lib/jekyll/version.rb`. +3. Update the **History document** as documented [here]({{ 'docs/maintaining/releasing-a-new-version/#update-the-history-document' | relative_url }}).
+ (**IMPORTANT: Do not run `rake site:generate` on the stable branch though**). +4. Copy the entire History section pertaining to current release and paste into a new tab / window of your text-editor. We will use this + temporary snippet at a future stage. +5. Commit changes to the version-file and History document with commit message `Release :gem: v[CURRENT_VERSION]`. +6. Push commit to upstream remote `jekyll/jekyll` at GitHub. + +## Publish release post + +1. Ensure the `Release Gem` workflow has completed successfully. +2. Merge release-post pull request to `master`. + +## Update default branch to reflect release off the stable branch + +1. Locally, check out `master` and ensure it is up-to-date with its remote counterpart at `jekyll/jekyll` at GitHub. +2. Update History document using the snippet in the temporary tab / window created earlier. The various sections in the History document are + primarily in reverse chronological order and secondarily scoped to the semver-major-version. For example, a release section for `v3.9.2` + will be listed above the section for `v3.9.1` but under release sections for v4.x. + The snippet stashed earlier has to be injected into the correct location manually. +3. Optionally, update `VERSION` string in `lib/jekyll/version.rb`. (*If existing version is lesser than latest version*). +4. Now **run `rake site:generate`** to update various meta files: + - docs/_config.yml + - docs/_docs/history.md + - docs/latest_version.txt +5. Commit changes to various meta files with commit message `Release :gem: v[CURRENT_VERSION]`. +6. Push commit to upstream remote. + +## Publish GitHub Release + +Unlike releases cut off the `master` branch, our JekyllBot does not automatically create and publish a GitHub Release for tags created from +*non-default* branches. Therefore, the maintainer has to **manually create and publish** the concerned GitHub Release. +1. Choose the newly pushed tag. +2. Title is same as the name of the selected tag. +3. The release snippet stashed previously forms the body. +4. Delete the snippet's title (`## x.y.z / YYYY-MM-DD`) from the release body. +5. Publish. + +Note: The GitHub Release may optionally be *drafted* prior to updating the default branch and then *published* immediately after pushing the +update commit to the default branch to streamline the procedure.