<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="generator" content="Jekyll v3.8.3">
<link type="application/atom+xml" rel="alternate" href="https://jekyllrb.com/feed.xml" title="Jekyll • Simple, blog-aware, static sites">
<link rel="alternate" type="application/atom+xml" title="Recent commits to Jekyll’s master branch" href="https://github.com/jekyll/jekyll/commits/master.atom">
<link rel="preconnect" href="https://fonts.gstatic.com/" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:300,300italic,400,400italic,700,700italic,900">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css">
<link rel="stylesheet" href="/css/screen.css">
<link rel="icon" type="image/x-icon" href="/favicon.ico">
<!-- Begin Jekyll SEO tag v2.4.0 -->
<title>Releasing a new version | Jekyll • Simple, blog-aware, static sites</title>
<meta name="generator" content="Jekyll v3.8.3">
<meta property="og:title" content="Releasing a new version">
<meta property="og:locale" content="en_US">
<meta name="description" content="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.">
<meta property="og:description" content="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.">
<link rel="canonical" href="https://jekyllrb.com/docs/maintaining/releasing-a-new-version/">
<meta property="og:url" content="https://jekyllrb.com/docs/maintaining/releasing-a-new-version/">
<meta property="og:site_name" content="Jekyll • Simple, blog-aware, static sites">
<meta property="og:type" content="article">
<meta property="article:published_time" content="2018-06-08T11:29:03-07:00">
<meta name="twitter:card" content="summary">
<meta name="twitter:site" content="@jekyllrb">
<meta name="google-site-verification" content="onQcXpAvtHBrUI5LlroHNE_FP0b2qvFyPq7VZw36iEY">
<script type="application/ld+json">
{"description":"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.","@type":"BlogPosting","url":"https://jekyllrb.com/docs/maintaining/releasing-a-new-version/","publisher":{"@type":"Organization","logo":{"@type":"ImageObject","url":"https://jekyllrb.com/img/logo-2x.png"}},"headline":"Releasing a new version","dateModified":"2018-06-08T11:29:03-07:00","datePublished":"2018-06-08T11:29:03-07:00","mainEntityOfPage":{"@type":"WebPage","@id":"https://jekyllrb.com/docs/maintaining/releasing-a-new-version/"},"@context":"http://schema.org"}</script>
<!-- End Jekyll SEO tag -->
<!--[if lt IE 9]>
<script src="/js/html5shiv.min.js"></script>
<script src="/js/respond.min.js"></script>
<![endif]-->
</head>
<body class="wrap">
<header>
<div class="flexbox">
<div class="center-on-mobiles">
<h1>
<a href="/" class="logo">
<span class="sr-only">Jekyll</span>
<img src="/img/logo-2x.png" width="140" height="65" alt="Jekyll Logo">
</a>
</h1>
</div>
<nav class="main-nav hide-on-mobiles">
<ul>
<li class="">
<a href="/">Home</a>
</li>
<li class="current">
<a href="/docs/home/">Docs</a>
</li>
<li class="">
<a href="/news/">News</a>
</li>
<li class="">
<a href="/help/">Help</a>
</li>
</ul>
</nav>
<div class="search hide-on-mobiles">
<input type="text" id="docsearch-input" placeholder="Search the docs…">
</div>
<div class="meta hide-on-mobiles">
<ul>
<li>
<a href="https://github.com/jekyll/jekyll/releases/tag/v3.8.3">v3.8.3</a>
</li>
<li>
<a href="https://github.com/jekyll/jekyll">GitHub</a>
</li>
</ul>
</div>
</div>
<nav class="mobile-nav show-on-mobiles">
<ul>
<li class="">
<a href="/">Home</a>
</li>
<li class="current">
<a href="/docs/home/">Docs</a>
</li>
<li class="">
<a href="/news/">News</a>
</li>
<li class="">
<a href="/help/">Help</a>
</li>
<li>
<a href="https://github.com/jekyll/jekyll">GitHub</a>
</li>
</ul>
</nav>
</header>
<section class="docs">
<div class="grid">
<div class="docs-nav-mobile unit whole show-on-mobiles">
<select onchange="if (this.value) window.location.href=this.value">
<option value="">Navigate the docs…</option>
<optgroup label="Getting Started">
<option value="/docs/home/">Welcome</option>
<option value="/docs/quickstart/">Quick-start guide</option>
<option value="/docs/installation/">Installation</option>
<option value="/docs/windows/">Jekyll on Windows</option>
<option value="/docs/usage/">Basic Usage</option>
<option value="/docs/structure/">Directory structure</option>
<option value="/docs/configuration/">Configuration</option>
</optgroup>
<optgroup label="Your Content">
<option value="/docs/frontmatter/">Front Matter</option>
<option value="/docs/posts/">Writing posts</option>
<option value="/docs/drafts/">Working with drafts</option>
<option value="/docs/pages/">Creating pages</option>
<option value="/docs/static-files/">Static Files</option>
<option value="/docs/variables/">Variables</option>
<option value="/docs/collections/">Collections</option>
<option value="/docs/datafiles/">Data Files</option>
<option value="/docs/assets/">Assets</option>
<option value="/docs/migrations/">Blog migrations</option>
</optgroup>
<optgroup label="Customization">
<option value="/docs/templates/">Templates</option>
<option value="/docs/includes/">Includes</option>
<option value="/docs/permalinks/">Permalinks</option>
<option value="/docs/pagination/">Pagination</option>
<option value="/docs/plugins/">Plugins</option>
<option value="/docs/themes/">Themes</option>
<option value="/docs/extras/">Extras</option>
</optgroup>
<optgroup label="Deployment">
<option value="/docs/github-pages/">GitHub Pages</option>
<option value="/docs/deployment-methods/">Deployment methods</option>
<option value="/docs/continuous-integration/">Continuous Integration</option>
</optgroup>
<optgroup label="Miscellaneous">
<option value="/docs/troubleshooting/">Troubleshooting</option>
<option value="/docs/sites/">Sites using Jekyll</option>
<option value="/docs/resources/">Resources</option>
<option value="/docs/upgrading/0-to-2/">Upgrading from 0.x to 2.x</option>
<option value="/docs/upgrading/2-to-3/">Upgrading from 2.x to 3.x</option>
</optgroup>
<optgroup label="Meta">
<option value="/docs/contributing/">Contributing</option>
<option value="/docs/maintaining/">Maintaining Jekyll</option>
<option value="/docs/conduct/">Code of Conduct</option>
<option value="/docs/history/">History</option>
</optgroup>
</select>
</div>
<div class="unit four-fifths">
<article>
<div class="improve right hide-on-mobiles">
<a href="https://github.com/jekyll/jekyll/edit/master/docs/_docs/maintaining/releasing-a-new-version.md"><i class="fa fa-pencil"></i> Improve this page</a>
</div>
<h1>Releasing a new version</h1>
<p class="note info"><strong>This guide is for maintainers.</strong> These special people have <strong>write access</strong> 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.</p>
<p>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 hestitate to contact the other maintainers if you feel unsure or don’t know what to do next.</p>
<h3 id="bump-the-version">Bump the version</h3>
<p>The only important place you need to manually bump the version is in <code class="highlighter-rouge">lib/jekyll/version.rb</code>. Adjust that, and everything else should work fine.</p>
<h3 id="update-the-history-document">Update the history document</h3>
<p>Replace the first header of the history document with a version milestone. This looks like the following:</p>
<div class="language-diff highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gd">-## HEAD
</span><span class="gi">+## 3.7.1 / 2018-01-25
</span></code></pre></div></div>
<p>Adjust the version number and the date. The <code class="highlighter-rouge">## HEAD</code> heading will be regenerated next time a pull request is merged.</p>
<p>Once you’ve done this, update the website by running the following command:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bundle <span class="nb">exec </span>rake site:generate
</code></pre></div></div>
<p>This updates the website’s changelog, and pushes the versions in various other places.</p>
<p>It’s recommended that you go over the <code class="highlighter-rouge">History.markdown</code> 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.</p>
<h2 id="write-a-release-post">Write a release post</h2>
<p>In case this isn’t done already, you can generate a new release post using the included <code class="highlighter-rouge">rake</code> command:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bundle <span class="nb">exec </span>rake site:releases:new[3.8.0]
</code></pre></div></div>
<p>where <code class="highlighter-rouge">3.8.0</code> 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:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>git shortlog <span class="nt">-sn</span> master...v3.7.2
</code></pre></div></div>
<p>where, again <code class="highlighter-rouge">v3.7.2</code> is the last release. Be sure to open a pull request for your release post.</p>
<h3 id="push-the-version">Push the version</h3>
<p>Before you do this step, make sure the following things are done:</p>
<ul>
<li>You have permission to push a new gem version to RubyGems</li>
<li>You’re logged into RubyGems on your command line</li>
<li>A release post has been prepared, and is ideally already live</li>
<li>All of the prior steps are done, committed, and pushed to <code class="highlighter-rouge">master</code>
</li>
</ul>
<p>Really the only thing left to do is to run this command:</p>
<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code>bundle <span class="nb">exec </span>rake release
</code></pre></div></div>
<p>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, <a href="https://github.com/jekyllbot" class="user-mention">@jekyllbot</a> should take care of that.</p>
<p>And then, you’re done! <img class="emoji" title=":tada:" alt=":tada:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f389.png" height="20" width="20"> Feel free to celebrate!</p>
<p>If you have access to the <a href="https://twitter.com/jekyllrb">@jekyllrb</a> Twitter account, you should tweet the release post from there. If not, just ask another maintainer to do it or to give you access.</p>
<h2 id="for-non-core-gems">For non-core gems</h2>
<p>If you’re not a maintainer for <code class="highlighter-rouge">jekyll/jekyll</code>, the procedure is much simpler in a lot of cases. Generally, the procedure still looks like this:</p>
<ul>
<li>Bump the gem version manually, usually in <code class="highlighter-rouge">lib/<plugin_name>/version.rb</code>
</li>
<li>Adjust the history file</li>
<li>Run <code class="highlighter-rouge">bundle exec rake release</code> or <code class="highlighter-rouge">script/release</code>, depending on which of the two exists</li>
<li>Rejoice</li>
</ul>
<p>Be sure to ask your project’s maintainers if you’re unsure!</p>
</article>
</div>
<div class="unit one-fifth hide-on-mobiles">
<aside>
<h4>Getting Started</h4>
<ul>
<li class=""><a href="/docs/home/">Welcome</a></li>
<li class=""><a href="/docs/quickstart/">Quick-start guide</a></li>
<li class=""><a href="/docs/installation/">Installation</a></li>
<li class=""><a href="/docs/windows/">Jekyll on Windows</a></li>
<li class=""><a href="/docs/usage/">Basic Usage</a></li>
<li class=""><a href="/docs/structure/">Directory structure</a></li>
<li class=""><a href="/docs/configuration/">Configuration</a></li>
</ul>
<h4>Your Content</h4>
<ul>
<li class=""><a href="/docs/frontmatter/">Front Matter</a></li>
<li class=""><a href="/docs/posts/">Writing posts</a></li>
<li class=""><a href="/docs/drafts/">Working with drafts</a></li>
<li class=""><a href="/docs/pages/">Creating pages</a></li>
<li class=""><a href="/docs/static-files/">Static Files</a></li>
<li class=""><a href="/docs/variables/">Variables</a></li>
<li class=""><a href="/docs/collections/">Collections</a></li>
<li class=""><a href="/docs/datafiles/">Data Files</a></li>
<li class=""><a href="/docs/assets/">Assets</a></li>
<li class=""><a href="/docs/migrations/">Blog migrations</a></li>
</ul>
<h4>Customization</h4>
<ul>
<li class=""><a href="/docs/templates/">Templates</a></li>
<li class=""><a href="/docs/includes/">Includes</a></li>
<li class=""><a href="/docs/permalinks/">Permalinks</a></li>
<li class=""><a href="/docs/pagination/">Pagination</a></li>
<li class=""><a href="/docs/plugins/">Plugins</a></li>
<li class=""><a href="/docs/themes/">Themes</a></li>
<li class=""><a href="/docs/extras/">Extras</a></li>
</ul>
<h4>Deployment</h4>
<ul>
<li class=""><a href="/docs/github-pages/">GitHub Pages</a></li>
<li class=""><a href="/docs/deployment-methods/">Deployment methods</a></li>
<li class=""><a href="/docs/continuous-integration/">Continuous Integration</a></li>
</ul>
<h4>Miscellaneous</h4>
<ul>
<li class=""><a href="/docs/troubleshooting/">Troubleshooting</a></li>
<li class=""><a href="/docs/sites/">Sites using Jekyll</a></li>
<li class=""><a href="/docs/resources/">Resources</a></li>
<li class=""><a href="/docs/upgrading/0-to-2/">Upgrading from 0.x to 2.x</a></li>
<li class=""><a href="/docs/upgrading/2-to-3/">Upgrading from 2.x to 3.x</a></li>
</ul>
<h4>Meta</h4>
<ul>
<li class=""><a href="/docs/contributing/">Contributing</a></li>
<li class=""><a href="/docs/maintaining/">Maintaining Jekyll</a></li>
<li class=""><a href="/docs/conduct/">Code of Conduct</a></li>
<li class=""><a href="/docs/history/">History</a></li>
</ul>
</aside>
</div>
<div class="clear"></div>
</div>
</section>
<footer>
<div class="grid">
<div class="unit one-third center-on-mobiles">
<p>The contents of this website are <br>© 2018 under the terms of the <a href="https://github.com/jekyll/jekyll/blob/master/LICENSE">MIT License</a>.</p>
</div>
<div class="unit two-thirds align-right center-on-mobiles">
<p>
Proudly hosted by
<a href="https://github.com">
<img src="/img/footer-logo.png" width="100" height="30" alt="GitHub • Social coding">
</a>
</p>
</div>
</div>
</footer>
<script>
var anchorForId = function (id) {
var anchor = document.createElement("a");
anchor.className = "header-link";
anchor.href = "#" + id;
anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>";
anchor.title = "Permalink";
return anchor;
};
var linkifyAnchors = function (level, containingElement) {
var headers = containingElement.getElementsByTagName("h" + level);
for (var h = 0; h < headers.length; h++) {
var header = headers[h];
if (typeof header.id !== "undefined" && header.id !== "") {
header.appendChild(anchorForId(header.id));
}
}
};
document.onreadystatechange = function () {
if (this.readyState === "complete") {
var contentBlock = document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0];
if (!contentBlock) {
return;
}
for (var level = 1; level <= 6; level++) {
linkifyAnchors(level, contentBlock);
}
}
};
</script>
<!-- Google Analytics (https://www.google.com/analytics) -->
<script>
!function(j,e,k,y,l,L){j.GoogleAnalyticsObject=y,j[y]||(j[y]=function(){
(j[y].q=j[y].q||[]).push(arguments)}),j[y].l=+new Date,l=e.createElement(k),
L=e.getElementsByTagName(k)[0],l.src='https://www.google-analytics.com/analytics.js',
L.parentNode.insertBefore(l,L)}(window,document,'script','ga');
ga('create', 'UA-50755011-1', 'jekyllrb.com');
ga('send', 'pageview');
</script>
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script type="text/javascript"> docsearch({
apiKey: '50fe39c839958dfad797000f33e2ec17',
indexName: 'jekyllrb',
inputSelector: '#docsearch-input',
enhancedSearchInput: true,
debug: false // Set debug to true if you want to inspect the dropdown
});
</script>
</body>
</html>