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.
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 you do publish an incomplete gem version, we can always skip that one. Don’t hesitate to contact the other maintainers if you feel unsure or don’t know what to do next.
Bump the version
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
Replace the first header of the history document with a version milestone. This looks like the following:
-## HEAD +## 3.7.1 / 2018-01-25
Adjust the version number and the date. The
## HEAD heading will be regenerated next time a pull request is merged.
Once you’ve done this, update the website by running the following command:
bundle exec rake site:generate
This updates the website’s changelog, and pushes the versions in various other places.
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
bundle exec rake site:releases:new[3.8.0]
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:
git shortlog -sn master...v3.7.2
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
Really the only thing left to do is to run this command:
bundle exec rake release
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.
And then, you’re done! Feel free to celebrate!
If you have access to the @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.
Build the docs
We package our documentation as a Gem for offline use.
This is done with the jekyll-docs 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:
- Bump the gem version manually, usually in
- Adjust the history file
bundle exec rake releaseor
script/release, depending on which of the two exists
Be sure to ask your project’s maintainers if you’re unsure!