Simplify macOS installation docs

[monfresh]

This is a 🔦 documentation change.

Summary

Instead of providing various options for installing Ruby, it's better to
stick to a single reliable solution: using a version manager. This
drastically simplifies this doc and makes it more maintainable.

Over the past 10 years, I've maintained detailed tutorials for properly
installing Ruby on a Mac. I've helped thousands of people, and I've seen
the same issues over and over.

Context

Per @ashmaroli's request here:

#8784 (comment)

I've linked to my Jekyll installation guide and I pledge to keep it up
to date, as I have with my other Ruby on Mac guides over the past ten
years.

Here's a collection of tweets from grateful people who have benefited
from my guides and script for setting up a proper Ruby environment on a
Mac:

https://twitter.com/monfresh/timelines/1480261956988596228

[monfresh]

In the past ten years of installing Ruby on a Mac on every OS X and macOS release, I have never had to set SDKROOT. This is absolutely not needed when using Homebrew to install a Ruby version manager.

[monfresh]

We should never ask people to install gems with sudo. When installing Ruby with a version manager, sudo is never needed.

[monfresh]

File permissions problems are only an issue when trying to install gems using the system Ruby. When installing Ruby with a reliable version manager like chruby, sudo is never needed, and there aren't any file permissions problems.

Since we are discouraging using the system Ruby, this section is no longer needed.

[monfresh]

This entire local install section only applies when using the system Ruby. When using a version manager like chruby, it takes care of setting the PATH, and therefore we can eliminate this whole section, and the complexity of having to set the PATH and remembering to update it to match the Ruby version.

[monfresh]

While Homebrew is an option for installing Ruby, I don't recommend mentioning it because eventually it will cause people confusion and headaches when they need to work with different projects that use different versions of Ruby.

Given that installing Ruby with a version manager is just as easy, and it has the additional benefit of supporting multiple versions at the same time, we should favor it. People prefer to be given clear instructions that will serve them in the long term, as opposed to making them choose between various options that they don't fully understand and that might not work well for them.

Furthermore, the Homebrew gems path that needs to be added to the PATH depends on the version of Ruby that was installed with Homebrew, which means these instructions below only work if someone installed Ruby 3.0.x. Sure, we could update these instructions to say to replace 3.0 with the first 2 digits of the Ruby version, but why make things more complicated than necessary?

[monfresh]

These are the OSes officially supported by Homebrew, and since we're using Homebrew to install a version manager, we have to mirror what Homebrew supports.

[monfresh]

Homebrew automatically installs the command line tools if they're not already there, and since we're installing Ruby via chruby, which in turn gets installed via Homebrew, this step is redundant.

[mattr-]

Every single comment you've left on this PR is a criticism of what was here before. Why is that necessary? We can see for ourselves the changes you've made and if we have questions, we'll ask them.

Based on your attitude towards other contributors prior work, as well as the fact that this update links to your website rather than providing actual content, I'm closing this. I appreciate the time and effort that went into making these changes but I don't think this update is for us.

[monfresh]

@mattr- I'm sorry my comments came off as criticisms. That was not at all the intention. Most of them are facts to provide the reasoning behind removing those sections. When I make changes, I like to provide details that explain why. I was just trying to be thorough rather than just removing a lot of content without explanation.

As for linking to my website, that's because @ashmaroli specifically asked me to here: #8784 (comment)

He specifically said to just link to my site:

You need not port the entire contents of your blog post to our documentation, just a section-heading, a brief preface and a link to your blog post will do. (Yes, do note the navigation to an external third-party site (your blog)).

The reason why he asked me to do this is because my guide has helped a lot of people who have been stuck trying to install Jekyll on Mac.

[ashmaroli]

as well as the fact that this update links to your website rather than providing actual content, I'm closing this.

@mattr- The author opened this pull request as a response to my request #8784 (comment)

So, I will shoulder the blame for that action and apologize for making that call.

[mattr-]

When I make changes, I like to provide details that explain why. I was just trying to be thorough rather than just removing a lot of content without explanation.

I appreciate the attention to detail. In the future, it's more beneficial to comment on the additions (IOW the green bits in a PR diff), rather than the subtractions (the red parts). This is a small thing but it makes a big difference because the comment is on your change, why it's there, and it makes the comments about your work, rather than someone else's work.

Also, I'm going to apologize because I didn't pay close enough attention to the words in the PR description and the linked comments. I'm sorry.

If we can fix the issues with the spelling action, let's reset things and review this a bit more objectively.

[monfresh]

The spell check is complaining about my name moncefbelyamani and preinstalled. The latter is a valid word according to the Dictionary app on my Mac.

What is the proper file to add these exceptions to? Is it .github/actions/spelling/expect.txt?

[monfresh]

I added those exceptions to expect.txt and the Spell Check action is passing now.

[monfresh]

Also, thanks for reopening the PR and your constructive criticism. I can see how my changes came off with the wrong tone. I apologize. I'm really passionate about this topic and can get carried away sometimes.

I thought about it some more, and I think I have a good middle ground. I propose to add the basic instructions for installing Ruby with chruby, similar to the current rbenv instructions, and then link to my more comprehensive guide for further setup and details, and for those who might have already tried to set up a dev environment but are running into issues.

One of the reasons I favor chruby is because you can use gems right after installing them, and it installs gems separately in each version of Ruby. Whereas with rbenv, you sometimes have to restart the terminal (or open a new tab) for things to be recognized. This is a common source of confusion.

For example, after installing a Ruby version and setting it with rbenv global, it doesn't always recognize it right away. Similarly, after installing a gem like Rails, rails -v doesn't work right away; you need to restart the terminal. With chruby, this isn't an issue that I can recall. This doesn't seem to be an issue when installing Jekyll with rbenv, but I prefer to recommend tools that will work consistently across various gems so people aren't surprised.

[monfresh]

@mattr- I just pushed a commit that adds instructions for installing Ruby with chruby, and I also added a note about adding webrick if using Ruby 3.x, which is another common issue people run into.

I think it looks much better now than what I originally had. I'd love to hear your thoughts.

[ashmaroli]

If you're able to edit this page on your local system, I recommend limiting line-lengths to 120 chars so that text-editors that do not soft wrap lines do not force extended horizontal scrolling.

[monfresh]

Thanks for the feedback. I just pushed the changes. I typically set the line length to 80 characters for readability, but I just realized that my Sublime Text settings were just wrapping at 80 characters, and not actually setting each line to 80 chars.

If you prefer 120, I'm happy to make the lines longer.

[ashmaroli]

If you prefer 120, I'm happy to make the lines longer.

There is no hard preference. Our source already contains documents with lines at 80 chars.
So, all good.

[monfresh]

Sounds good. Any other changes you'd like me to make? And should I squash the commits?

[ashmaroli]

I'm not a macOS user. Therefore, will take this at face-value.

[ashmaroli]

And should I squash the commits?

The commits will be squashed automatically at the time of merging.

[monfresh]

Hello. Any idea when this might be merged?

[mattr-]

@jekyllbot: merge +docs

[mattr-]

Sorry! I thought this was merged already after the first approval.

[monfresh]

No worries. Thanks for merging!

[bamr87]

Have these new instructions been tested? I followed these new steps on a new install of Monterey 12.4 and it took forever to install, and still didn't work...

After restarting the terminal, it said that it couldn't find Ruby 3.1.0, and ruby -v returned the system version. In addition, the hostname name was changed the my machine's ID.

[monfresh]

@bamr87 I think the issue might be with this line in the instructions, which is not up to date with the latest version of Ruby:

echo "chruby ruby-3.1.1" >> ~/.zshrc

Try this instead:

echo "chruby ruby-3.1.2" >> ~/.zshrc

To verify if chruby was properly installed, try running chruby. It should show all versions that are present on your machine. You can switch to one of those versions like this:

chruby 3.1.2

Then when you do ruby -v, it should show 3.1.2

I will update the version in the Jekyll docs.

I keep my tutorial up to date, and I will try to remember to update the Jekyll docs as well.

[bamr87]

@monfresh - Thanks for the info. I should have paid more attention to the version, and that seemed to have been the issue.

It would be helpful to note in these instructions that the zsh profile should be updated for every new version.

Also, it might be worth noting that the hostname of a user's computer will also change. I don't know exactly why, but my first run through updated my hostname to the computer ID, and this second run through updated it to something slightly different. See screenshot.

Right side is before, and left is after reopening the terminal.

[monfresh]

Yes, I will make a note in the instructions about updating the shell profile. Thanks for the suggestion!

These kinds of issues are the reason why I built the Ruby on Mac script that takes care of everything for you. It automatically updates the shell profile (whether you're using zsh, bash, or fish) with whatever version got installed so that they are always in sync. And it comes with a rom alias that you can run regularly to keep everything up to date.

As for the hostname, I very much doubt it has anything do with installing Ruby. This is the first time in 10 years of helping people install Ruby on their Mac that I've heard of this issue.