Figure out why Gemfile and Gemfile.lock are causing issues

[choldgraf]

In a few threads now (e.g., #152) we've run into issues where a Gemfile.lock that was out-of-date caused issues in the book building.

Can we

1. Diagnose why this is an issue, and 2
2. Figure out a means (either documentation or tech) that can make this less problematic

[emdupre]

Right now I have some documentation on running the upgrade under the docker section, but it'd be great to think about a better place for this !

[jasmainak]

I think people need to remember to upgrade the jupyter book. I couldn't find it in the documentation ...

[emdupre]

It's clearly too short of a mention on my part :)

If you navigate to http://0.0.0.0:4000/jupyter-book/ in your browser, you should see a preview copy of your book. If you instead see an error, please try to update your local book; see the Jupyter Book FAQ section for more details on how to do so.

Where would this be better placed ?

[jasmainak]

Ahhhh ... haha I missed it too. I would place it as a command, saying what to do:

$ jupyter-book upgrade 

actually, now I am not sure if this would solve the problem. Where does the upgrade get the template book from? It seems to me that you need to upgrade your python package and run this command. Otherwise, it won't upgrade. Since it does not get the template from the web but from the installed repository (?)

[emdupre]

Maybe we actually just shouldn't be distributing a Gemfile.lock:

https://ben.balter.com/jekyll-style-guide/gitignore/

[emdupre]

Also, sorry, just to actually address @choldgraf 's question of why this is an issue !

jekyll serve is trying to rely on the Gemfile.lock to determine the exact versions of all gems that should be used in serving the site. When I built the Docker image I couldn't find a way to match those exact versions in a "light" environment -- right now, the Docker image is building off of one that Jekyll distributes, where they worked to shrink the filesize down. So if you try to run the site using the created container, you need gem versions that are not accessible in the environment. What is in the environment can run the site just fine, and when you delete the Gemfile.lock it will go ahead and do so. But as long as the Gemfile.lock exists it tries to match exactly those gem versions -- and it can't 😞

So I see three possible solutions:

1. Try to rebuild the docker image to match the original Gemfile.lock, maybe for a slightly larger image
2. Update the documentation to make clear why this is happening and what to do
3. Just stop distributing the Gemfile.lock, as it sounds this isn't necessary -- especially for GitHub pages sites

Would love to know what direction seems most reasonable for moving forward !

[choldgraf]

hmmm, I kinda feel like "don't use gemfile.lock" makes the most sense. Doesn't it get created when you run the install?

[emdupre]

Yes, but only if it's not already existing !

[choldgraf]

hmmm, so is there any downside to removing it from the copied template? (I can't think of any)