New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Bundler Installation Instructions #6828

Merged
merged 2 commits into from Mar 16, 2018

Conversation

Projects
None yet
8 participants
@mkasberg
Contributor

mkasberg commented Mar 5, 2018

This commit addresses issue #6800. Specifically, this commit adds a
section for installing Jekyll using Bundler (as an alternative to the
gem command or RVM).

In addition, clean up the surrounding instructions a bit, and add some
helpful hints. One hint for Ubuntu users to get started quickly, and one
hint for people who run into permissions problems with gem install jekyll.

Improve Installation Instructions
This commit addresses issue #6800. Specifically, this commit adds a
section for installing Jekyll using Bundler (as an alternative to the
gem command or RVM).

In addition, clean up the surrounding instructions a bit, and add some
helpful hints. One hint for Ubuntu users to get started quickly, and one
hint for people who run into permissions problems with `gem install
jekyll`.
bundle install --path vendor/bundle # Set install path to ./vendor/bundle
bundle add jekyll # Add & install Jekyll gem
```

This comment has been minimized.

@ashmaroli

ashmaroli Mar 5, 2018

Member

I'm not a fan of this method though..
A new user would get confused by having to run bundle exec jekyll new . and be greeted by an error message.,. while elsewhere in the docs, we simply instruct users to initialize a jekyll project with
jekyll new [jekyll-project-path]

This comment has been minimized.

@DirtyF

DirtyF Mar 5, 2018

Member

We could distinct new with defaults from blank (working on a PR to have a working default directory structure. with blank)

Then, add Jekyll to your project's dependencies:
```sh
cd my-jekyll-project

This comment has been minimized.

@ashmaroli

ashmaroli Mar 5, 2018

Member

you can't cd into a path that doesn't exist before-hand..

First, install Bundler (as a system-wide gem):
```sh
sudo gem install bundler

This comment has been minimized.

@pathawks

pathawks Mar 5, 2018

Member

If the goal is to avoid permissions issues, using sudo is a non-starter.

This comment has been minimized.

@DirtyF

DirtyF Mar 5, 2018

Member

what is the recommended method then?

This comment has been minimized.

@pathawks

pathawks Mar 5, 2018

Member

gem install --user-install bundler

This comment has been minimized.

@mkasberg

mkasberg Mar 6, 2018

Contributor

Agreed. I've always installed Bundler along with Ruby via apt on Ubuntu, but if you're on LTS it's a really old version of Bundler... But you're right, we shouldn't recommend that.

@@ -37,11 +46,34 @@ Before you start, make sure your system has the following:
</p>
</div>
## Install & Use Jekyll with Bundler

This comment has been minimized.

@pathawks

pathawks Mar 5, 2018

Member

I don’t know if we want this ./vendor/bundle method to be presented first, as if it is the default/recommended method :/

<p>
The above command performs a system-wide install of jekyll (on most
systems). If you get a permissions error, you can either run the command as root
(<code>sudo gem install jekyll</code>) or use

This comment has been minimized.

@pathawks

pathawks Mar 5, 2018

Member

This always leads to conflicts with multiple versions of Jekyll being installed. There have been countless bug reports from users who installed Jekyll using sudo without understanding what that meant. Let’s recommend installing to ~/ instead of using sudo

This comment has been minimized.

@mkasberg

mkasberg Mar 6, 2018

Contributor

Good point. No sudo.

The above command performs a system-wide install of jekyll (on most
systems). If you get a permissions error, you can either run the command as root
(<code>sudo gem install jekyll</code>) or use
<a href="https://rvm.io/gemsets/basics">RVM</a> to manage your Gems.

This comment has been minimized.

@pathawks

pathawks Mar 5, 2018

Member

Isn’t RVM for managing Ruby versions? I have always used RVM in addition to Bundler. Can we provide any more detail here?

This comment has been minimized.

@DirtyF

DirtyF Mar 5, 2018

Member

is there a simpler method than the one listed here?

sudo apt-get install libgdbm-dev libncurses5-dev automake libtool bison libffi-dev
gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
curl -sSL https://get.rvm.io | bash -s stable
source ~/.rvm/scripts/rvm
rvm install 2.5.0
rvm use 2.5.0 --default
ruby -v

This comment has been minimized.

@oe

oe Mar 5, 2018

Member

The only simpler method I can think of is if RVM is in your system's package manager repositories, I'm afraid.

@@ -28,6 +29,14 @@ Before you start, make sure your system has the following:
</p>
</div>
<div class="note info">

This comment has been minimized.

@pathawks

pathawks Mar 5, 2018

Member

Do we really need three notes in a row?
Is there a better way to present this?

This comment has been minimized.

@DirtyF

DirtyF Mar 5, 2018

Member

Agreed. Let's do a section per system.

@DirtyF DirtyF added the documentation label Mar 5, 2018

@DirtyF DirtyF requested a review from jekyll/documentation Mar 5, 2018

@DirtyF

This comment has been minimized.

Member

DirtyF commented Mar 5, 2018

Thanks @mkasberg, we need to do better on install instructions for different systems.

This feels too custom/advanced for a default install compared to the instructions for installing jekyll on Linux on CloudCannon.

I don't mind adding a dedicated Install on GNU/Linux section as long as there's a compromise from linux users on what should be the simplest default working method. What I see is that experienced command line users have each one a preferred method and we can't list them all. We just need a good default method.

This does not prevent to also add advanced methods and custom options like the --path you show here.

Resources:

@oe

Our installation section is now so big, we definitely need a table of contents or something of the like. Also I'm not sure whether putting the bundler method first is the right choice here, while it is probably the right-est method, it's not the easiest one and not the one we should recommend.

To use Jekyll with [Bundler](https://bundler.io/), add it as a
dependency of your project. It can be installed in a sub-directory of the
project. This avoids permissions issues, and also allows you to use different

This comment has been minimized.

@oe

oe Mar 5, 2018

Member

permissions -> permission

The above command performs a system-wide install of jekyll (on most
systems). If you get a permissions error, you can either run the command as root
(<code>sudo gem install jekyll</code>) or use
<a href="https://rvm.io/gemsets/basics">RVM</a> to manage your Gems.

This comment has been minimized.

@oe

oe Mar 5, 2018

Member

The only simpler method I can think of is if RVM is in your system's package manager repositories, I'm afraid.

@mkasberg

This comment has been minimized.

Contributor

mkasberg commented Mar 6, 2018

Thanks for all the comments everyone, it's all good feedback.

I think perhaps this pull request is changing too much too quickly. @oe brings up a good point that while Bundler may be preferable for some users, perhaps it's not a good default if you're going for the simplest method. Also, I don't do jekyll new too often, so I wasn't thinking about that... I'll probably close this pull request (unmerged), but I wouldn't mind following up with a simpler pull request if there's some kind of consensus.

I guess the original thing that I wanted to fix is to make sure a new user knows what to do if they run into permissions problems at the gem install jekyll step. Particularly if they haven't used Ruby before and just want to run Jekyll as easily as possible. I know there are lots of ways to go about it, but is there any kind of consensus on what might be best for new users?

@pathawks

This comment has been minimized.

Member

pathawks commented Mar 6, 2018

I guess the original thing that I wanted to fix is to make sure a new user knows what to do if they run into permissions problems at the gem install jekyll step. Particularly if they haven't used Ruby before and just want to run Jekyll as easily as possible.

Yes. 💯

This has been a very difficult problem for us to solve. On the one hand, we do not distribute or support Ruby or Bundler and aren't really setup to support users that are still trying to get those things installed. On the other hand, this is the biggest hurdle for new users getting started with Jekyll, and I am sure we would have happier users (and quite possibly more developers) if installing Jekyll were not by far the most difficult step toward using (or contributing to) Jekyll.

What makes it especially tricky is that, as on display in this thread, it seems there are as many different ways to install Jekyll as there are users using Jekyll. This means there isn't necessarily anything as simple as "Copy these three lines and paste them into a shell."

You have done a lot of good work here and it would be a shame to just close the PR. I wonder if this could be spun into a tutorial for installing Jekyll on Ubuntu or something similar? Maybe for users that want to use a Docker container or install Jekyll system wide, make sure you have these dependencies and sudo install everything.

Thoughts @DirtyF?

@crispgm

This comment has been minimized.

Member

crispgm commented Mar 6, 2018

AFAIK, it's over lengthy for most users.

Shall we make a tl;dr as recommended installation method for OS with much population at the top?

@DirtyF

This comment has been minimized.

Member

DirtyF commented Mar 6, 2018

We need to rethink the whole install page, so that's it's easier to follow for each OS:

I was thinking of something like:

jekyll-install-macos

We would need help on the GNU/Linux part. Anyone willing to contribute?

@DirtyF DirtyF assigned adamhollett and unassigned adamhollett Mar 6, 2018

@mkasberg

This comment has been minimized.

Contributor

mkasberg commented Mar 6, 2018

I could spin this PR off into a tutorial, "Using Jekyll as a Bundler Dependency," that's probably a better place for it. It can be done without the sudo gem install bundler step... I just need to figure out the best/simplest way.

I'm also willing to help with writing installation instructions for GNU/Linux, I think the idea of separate sections probably makes sense.

@DirtyF DirtyF self-assigned this Mar 6, 2018

Move Bundler Instructions to Tutorial
Based on discussion in PR #6828, move the instructions for setting up a
project with Bundler to a tutorial. This is a better place for it since
the installation instructions are targeted primarily at new users, and
it can be confusing to list several different installation methods -
particularly more complex ones.

@mkasberg mkasberg changed the title from Improve Installation Instructions to Add Bundler Installation Instructions Mar 7, 2018

@pathawks

This is fantastic! I really like having this in the Tutorials section!

@pathawks

This comment has been minimized.

Member

pathawks commented Mar 7, 2018

I really like this document conceptually, but I'm a bit tired at the moment so somebody from @jekyll/documentation should also review 😴👍

because Jekyll gets confused if the Gemfile already exists.
```sh
bundle exec jekyll new --force --skip-bundle .

This comment has been minimized.

@ashmaroli

ashmaroli Mar 7, 2018

Member

you missed the 'dot' . here.. bundle exec jekyll new .

This comment has been minimized.

@oe

oe Mar 7, 2018

Member

@ashmaroli the dot is included here, at the end of the line

This comment has been minimized.

@ashmaroli

ashmaroli Mar 7, 2018

Member

gosh.. I did not see that..
guess my brain registered it as a 'full-stop'.. 😛

@oe

oe approved these changes Mar 16, 2018

This is really good!

@DirtyF

This comment has been minimized.

Member

DirtyF commented Mar 16, 2018

@jekyllbot: merge +docs

@jekyllbot jekyllbot merged commit a275faa into jekyll:master Mar 16, 2018

3 checks passed

WIP ready for review
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details

@mkasberg mkasberg referenced this pull request Mar 20, 2018

Closed

Add ruby environment instructions to Install guide #6800

2 of 2 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment