What Happens When You Don't Specify a Version in Your Gemfile


This is a video that I shared with the people on my list long before posting it on this site. Join us for early access to more videos!

If you find this guide helpful, please spread the knowledge and tell people to join the list!

In this video, we go over the consequences of adding a gem to your Gemfile without specifying a version. Although the example uses a Jekyll site, this concept applies to any Ruby project.


Hi everyone. Today, we’ll go over common issues you might run into with Jekyll themes. And as always, I like to use real examples. So today’s episode is brought to you by Martin Roberts, who is a college professor who teaches courses on global digital media at Dartmouth College and Emerson College.

And he’s also written a book about Japanese popular music, also known as J-pop and his book is called Cornelius’s Fantasma. So check it out if that’s your jam. All right. So Martin, used my tutorial to deploy a Jekyll site, to GitHub pages and everything worked as expected. So then he wanted to try out a different theme, but couldn’t get it to work.

So he emailed me and asked for my help, and together, we worked through the issues and, and got everything working. And so we’ll recreate what Martin did to discover what kind of issues he ran into and why he ran into them and how to fix them.

All right. So I also have this GitHub Pages setup working already, and just to double check, we’re gonna run the server locally. So the full command you would have to run is bundle exec jekyll serve, which is quite a mouthful and takes a while to type. And so I have an alias or shortcut. All I have to do is type js and that will start the server. And the way that works is by creating what’s called an alias in your shell file. And if you’re not familiar with those, I have a tutorial on that.

So check it out. And so now everything is running. I will copy this server address over here, open a new tab. All right. Everything looks good. And another shortcut, instead of having to remember this numerical address, you can instead type localhost and that will work as well. All right. So now we want to install a theme called moving, which is the theme that Martin wanted to try out.

And if you don’t know off the top of your head where to find the theme or to find the code for the theme, or for any Ruby gem, you can always go to rubygems.org, which is where all Ruby gems are hosted, and look for it there. So we know the name of the theme is “moving” and most Jekyll themes are available as gems.

So we can start there. And looking at the description, sounds like what we’re looking for. So we can click through on that. And then at the bottom, there’s a homepage, which is typically where the source code lives. And so we click on through it. So it looks like it’s on GitHub.

Now another way to find the source code for a gem is through this service that I just discovered recently through the Ruby Weekly newsletter. It’s a website called gem.wtf, and you just go to gem.wtf and then slash and the name of the gem.

So in this case, moving, and it’ll take you directly to where its, where the source code lives, which is pretty neat. All right. So now let’s look through the Readme and we can see a screenshot of what the theme looks like, which is good, because then we’ll have an idea of what our local site should look like just to make sure the site is working.

We can also look at the demo which I’ve already opened here. All right. As the description says, it is quite minimal. It has a nice font. So this is what we’re expecting. We’re expecting to see something along these lines, once we install the theme. And the installation, it looks like we have two options: as a new blog, or adding it to an existing blog, which is typically how you want to add a theme.

And so we need to add the moving gem to our Gemfile, but we also want to comment out the minima theme, which is the default Jekyll theme. Cause you don’t want to have multiple themes at the same time. And it’s also a general best practice to make changes a bit at a time. That way, if something goes wrong, it’s easier to figure out which part went wrong.

And so if the only change we’re making right now is to replace the default theme with a new theme, then if something goes wrong, then we’ll know that it’s likely the theme. All right. And we’ll also have to change the config. All right, we’ll save that. And then we’ll stop the server using control-C as it says down here, and then we’ll need to run bundle install again, because we’ve added a new gem.

We have to re-install this new bundle and you can also just run bundle for short. And I have it even shorter with another alias. I just type bi and that’ll run bundle install. All right. So now we can run the server again. And now we should be able to refresh. Okay. So something definitely changed, but it doesn’t look quite right.

If you recall, this is the demo and this is what we have now, what it looks like is that the styling is missing. The layout is not, it doesn’t look quite right. The font doesn’t look quite right. So the way a website looks comes from CSS, which stands for cascading style sheets, and a website I like to use to show people the power of CSS, for those of you who might not be very familiar with it, is called csszengarden.com.

And this website has links to different versions of the site where the only difference is the CSS. So the text is the same. The HTML code itself is the same, but only the CSS has changed. So let’s click on this one for example. You see, it looks like a completely different website, right? But it’s still the same text. The structure in terms of the HTML is the same. It hasn’t changed. It’s just the layout and the backgrounds and the fonts.

And if we try a different theme, let’s try this garments theme. You see? So all of these make it look like very different websites and that’s all with, with CSS.

And so whenever you see a site that doesn’t look quite right in terms of the looks, that’s typically an issue with the CSS. So my guess is the CSS file is missing. And so how can we confirm that theory? Well, all browsers come with developer tools. Most browsers have them enabled by default, but in Safari you have to manually turn it on.

So if you haven’t already, you can go to the Safari preferences, and the keyboard shortcut for accessing the preferences for any Mac application is command comma. And in Safari, if you go to the advanced tab, and then at the bottom, there’s this checkbox: show develop menu in menu bar. So you want to keep that checked and then once that’s checked, you can open the developer tools with a keyboard shortcut: option-command-I.

All right. So you can see typically errors will show up in the console tab over here or in the network tab. And they’re typically in red that way they stand out and let you know that something’s wrong. And so this says that this file is not found. So it’s looking for a file called main dot CSS within the assets slash CSS folder.

All right. So something is requesting this file or mentioning it, but it’s nowhere to be found. So the browser can’t find it. All right. So let’s, let’s see if we can find it in our project. So I’m going to do shift-command-F in sublime text. Now we’ll look for main dot CSS, and in the second box right here, where it says “where”, I’ve excluded, this is what the minus sign means, the underscore site folder.

And then the asterisk means anything inside that folder. That’s because this is where the Jekyll site gets generated, but we’re only looking for the files, pre generation. And so let’s check for that. Okay, it’s not here, so it’s not in our main project. But the only thing we changed, if you recall, was the, was the moving theme and so the moving theme must somehow be, mentioning it.

And so when you add a gem to your Gemfile or a theme to your Gemfile, it doesn’t automatically add the theme’s files, source code files, into your project. It’s still available to your project, but they’re not inside your own project. So we have to look for them.

And so how can we do that? Well, any gem that you add to your project is available for you to view its source code locally by running bundle open, and then the name of the gem.

So in this case “moving”, and we’ll open that folder locally and I’ve done the keyboard shortcut command-K-B, which opens on the sidebar here, all of the folders and files of the moving gem. So we can do the same thing as before. Look for main dot CSS. Okay. So we can see that it’s referenced in this head dot HTML file right here.

But then when we look at the contents of the gem, the file’s not here. So this sounds like a bug with the gem, with the theme. It’s telling the browser to load the CSS file, but it didn’t include it. So now it makes sense that the browser can’t find it because it’s not here. Okay. So now let’s compare what we see here with what’s on GitHub, and let’s see if the file exists on GitHub.

We can go to view code. So there is an assets slash CSS folder, and it has two CSS files, but here main, the, the file extension is dot scss, not CSS. So how come the code that’s on GitHub it’s not the same as what we have locally?

So if we go back to Ruby gems, we can see that there were multiple versions released over time. So which version do we actually have? Well one way to find out when we opened the source code using bundle open moving, you can see at the top here that it says moving-0.1.0, which is the very first release. And another way to find out is to go to your Gemfile.lock file and look for moving there.

And you can see it installed 0.1.0. Well, that’s interesting how come it installed the very first release and not the latest one, 0.3.4? And to understand that, you need a basic understanding of how bundler and Gemfiles work.

And in this case, the reason is because we didn’t specify a version number when we added the gem, which is common, although not a best practice, for the very reason that we witnessed today.

And so the reason why bundler installed the very first version is because when you don’t specify a version, it tries to find the combination of gem versions that will make the whole project compatible, make all the gems within a project compatible with one another, because each gem has its own dependencies with maybe specific versions.

So if we go to 0.1.0, we can see that it depends on Jekyll version, at least 4.0, but less than 5.0. This is what this ~> sign means. It’s known as the pessimistic operator in Ruby. So in our case, in our project, what the pessimistic operator means when you have three digits specified, it means at least 4.2.0, but less than 4.3.

And when you only have two digits, it means at least 4.0, but less than 5.0. And now if we look at the latest version of the moving theme, we can see that they changed the versioning of the dependencies. So now they’re saying, at least 4.0.0, but less than 4.1, because when you specify three digits, the second digit can’t change.

So it’s anything at least 4.0.0, but less than 4.1, but we’re saying we want at least 4.2, which doesn’t work. And so bundler kept going down all the versions until it found one that was compatible. And in this case, the only one that was compatible was the very first release. And so that’s what was installed.

And I go over this also I have a tutorial called “how to update gems in your Gemfile”, and down here in the Gemfile versioning, I explain this in more detail, so check it out. But basically this is the, the first issue that Martin ran into, is that he ended up with a buggy initial version. And if we go back to rubygems.org, we can see that the gem maintainer released a second release on the same day.

So they probably realized they made a mistake and perhaps included that main dot CSS file in the second release. So the main issue here is that we didn’t specify a version and we ended up with a buggy version, which caused the styling to be missing. And so this is the main issue I wanted to go over in part one of this tutorial.

And in part two, we’ll specify a version, that way we can get the latest version of the theme, and see what kind of trade-offs that introduces. And once we are able to properly install the theme, we’ll see what other issues Martin ran into and how to fix those. So to recap today’s episode, what did we learn?

All right. Well, that’s it for this episode. See you in the next one.