dan
/
jekyll
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve maintainers guide on releasing a new version (#8928) 

Merge pull request 8928
This commit is contained in:
Ashwin Maroli 2022-01-08 21:12:31 +05:30 committed by GitHub
parent 7b7a286b4a
commit d4a4d951c5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 101 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

134
docs/_docs/maintaining/releasing-a-new-version.md
View File

@ -2,7 +2,8 @@
title: "Releasing a new version"
---
**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the contributions of others. You may find what is written here interesting, but it’s definitely not for everyone.
**This guide is for maintainers.** These special people have **write access** to one or more of Jekyll's repositories and help merge the
contributions of others. You may find what is written here interesting, but it's definitely not for everyone.
{: .note .info}
The most important thing to understand before making a release is that there's no need to feel nervous. Most things are revertable, and even if
@ -13,9 +14,54 @@ don't know what to do next.
The only important place you need to manually bump the version is in `lib/jekyll/version.rb`. Adjust that, and everything else should work fine.
### Update the history document
The version will mostly be of the format `"major.minor.patch"`. At times, we may decide to ship pre-releases which will be in the format
`"major.minor.patch.suffix"`. `suffix` is not standardized and may be anything like `pre.alpha1`, `pre.rc2`, or simply `beta3`, etc.
Replace the first header of the history document with a version milestone. This looks like the following:
To determine the correct version, consult the `## HEAD` section of our history document, `History.markdown`, first.
- If there's a subsection titled `Major Enhancements`
- Increment the `major` component of the version string and reset both `minor` and `patch` components to `0`.
- Add `suffix` if applicable.
- For example, `"3.9.1" => "4.0.0"` or, `"3.9.1 => "4.0.0.alpha1"`.
- Skip to next step in the release process.
- If there's a subsection titled `Minor Enhancements`
- Increment just the `minor` component and reset the patch component to `0`.
- Add `suffix` if applicable.
- For example, `"4.0.2" => "4.1.0"` or `"4.1.0" => "4.2.0.pre"`.
- Skip to next step in the release process.
- For anything else, increment just the `patch` component or `suffix` component as applicable. For example, `"4.0.2" => "4.0.3"` or
`"4.1.0.beta3" => "4.1.0.rc"`.
### Write a release post
In case this wasn't done already, you can generate a new release post scaffold using the included `rake` command:
```sh
bundle exec rake site:releases:new[3.8.0]
```
where `3.8.0` should be replaced with the new version.
Then, write the post. Be sure to thank all of the collaborators and maintainers who have contributed since the last release. You can generate
a log of their names using the following command:
```sh
git shortlog -sn master...v3.7.2
```
where `v3.7.2` is the git tag for the previous release. In case the tag doesn't exist in your repository, run:
```sh
git pull
```
Be sure to open a pull request for your release post once its finished.
### Update the History document
Replace the first header of `History.markdown` with a version milestone. This looks like the following:
```diff
- ## HEAD
@ -24,6 +70,40 @@ Replace the first header of the history document with a version milestone. This
Adjust the version number and the date. The `## HEAD` heading will be regenerated the next time a pull request is merged.
Rearrange the subsections (as a whole) based on decreasing priorities as illustrated below:
```
## 4.2.0 / 2020-12-14
### Major Enhancements
...
### Minor Enhancements
...
### Bug Fixes
...
### Security Fixes
...
### Optimization Fixes
...
### Development Fixes
...
### Site Enhancements
...
```
Once you've done this, update the website by running the following command:
```sh
@ -35,42 +115,28 @@ This updates the website's changelog, and pushes the versions in various other p
It's recommended that you go over the `History.markdown` file manually one more time, in case there are any spelling errors or such. Feel free
to fix those manually, and after you're done generating the website changelog, commit your changes.
## Write a release post
In case this isn't done already, you can generate a new release post using the included `rake` command:
```sh
bundle exec rake site:releases:new[3.8.0]
```
where `3.8.0` should be replaced with the new version. Then, write the post. Be sure to thank all of the collaborators and maintainers who have
contributed since the last release. You can generate a log of their names using the following command:
```sh
git shortlog -sn master...v3.7.2
```
where, again `v3.7.2` is the last release. Be sure to open a pull request for your release post.
### Push the version
Before you do this step, make sure the following things are done:
- You have permission to push a new gem version to RubyGems
- You're logged into RubyGems on your command line
- A release post has been prepared, and is ideally already live
- All of the prior steps are done, committed, and pushed to `master`
- A release post has been prepared, and is ideally already live via a prior pull request.
- All of the prior steps are done, especially the change to `lib/jekyll/version.rb` has been staged for commit.
- Commit staged changes to the local `master` branch preferably with commit message `"Release :gem: v[CURRENT_VERSION]"`.
Really the only thing left to do is to run this command:
The only thing left to do now is to run this command:
```sh
bundle exec rake release
git push upstream master
```
This will automatically build the new gem, make a release commit and tag and then push the new gem to RubyGems. Don't worry about creating a
GitHub release, @jekyllbot should take care of that.
where `upstream` references `git@github.com:jekyll/jekyll.git`.
And then, you're done! :tada: Feel free to celebrate!
This will trigger a GitHub Actions workflow that will automatically build the new gem, tag the release commit, push the tag to GitHub and
then finally, push the new gem to RubyGems. Don't worry about creating a GitHub release either, @jekyllbot will take care of that when the
release workflow publishes the new tag.
And then, if the workflow has completed successfully, you're done! :tada:
Feel free to celebrate!
If you have access to the [@jekyllrb](https://twitter.com/jekyllrb) Twitter account, you should tweet the release post from there. If not, just
ask another maintainer to do it or to give you access.
@ -79,16 +145,18 @@ ask another maintainer to do it or to give you access.
We package our documentation as a :gem: Gem for offline use.
This is done with the
[**jekyll-docs**](https://github.com/jekyll/jekyll-docs#building) repository, and more detailed instructions are provided there.
This is done with the [**jekyll-docs**](https://github.com/jekyll/jekyll-docs#building) repository, and more detailed instructions are
provided there.
## For non-core gems
If you're not a maintainer for `jekyll/jekyll`, the procedure is much simpler in a lot of cases. Generally, the procedure still looks like this:
If you're not a maintainer for `jekyll/jekyll`, the procedure is much simpler in a lot of cases. Generally, the procedure still looks like
this:
- Bump the gem version manually, usually in `lib/<plugin_name>/version.rb`
- Adjust the history file
- Run `bundle exec rake release` or `script/release`, depending on which of the two exists
- Commit changes to default branch preferably with message `"Release :gem: v[CURRENT_VERSION]"`
- Push to remote repository
- Rejoice
Be sure to ask your project's maintainers if you're unsure!