fastlane/docs

Install instructions use sudo and don't use bundler

bradyt opened this issue · 7 comments

bradyt commented

I am not really a Ruby user, so the instructions at https://docs.fastlane.tools/getting-started/android/setup/ can easily be my first experience with installing a Ruby executable. But the use of sudo in those instructions is off-putting, and it's not trivial to realize a simple way to avoid sudo with gem, as google results can take us into many other approaches.

I hope I'm not starting a flame war on the best ways to install gems without sudo. But --user-install seems like a quick, easy, idiomatic solution.

Additionally, I think we'll end up with warnings when installing fastlane in this way, with suggestions that we should use bundle exec. So why not suggest users install bundler right away? And following messages along, I seemed to get a suggestion to use bundle config set path 'vendor/bundle'.

So my suggestion is the following diff to be applied. I'd rather someone just edit the page to their liking, as I'd rather not stop to figure out this google signature in the pull request.

modified   docs/includes/installing-fastlane.md
@@ -10,6 +10,16 @@ Install _fastlane_ using
 # Using RubyGems
 sudo gem install fastlane -NV
 
+# Alternatively without sudo
+gem install --user-install fastlane -NV
+
+# Alternatively using bundler
+gem install --user-install bundler
+echo 'source "https://rubygems.org"\n\ngem "fastlane"' > Gemfile
+bundle config set path 'vendor/bundle'
+bundle install
+# bundle exec fastlane
+
 # Alternatively using Homebrew
 brew install fastlane
 ```
janpio commented

Installation is a complicated topic, but generally I agree.
What do you think @joshdholtz?

joshdholtz commented

I really like this feedback. I do think the installation page could use a good amount of rework. I do agree that we should suggest users use bundler first.

I'm totally down for reworking installation with the installs that will result in the best execution environment for the users first 👍

  • 👍1
bradyt commented

Okay, I think I came up with some more efficient, or smaller, changes.

modified   docs/includes/installing-fastlane.md
@@ -8,7 +8,7 @@ Install _fastlane_ using
 
 ```sh
 # Using RubyGems
-sudo gem install fastlane -NV
+[sudo] gem install [--user-install] fastlane -NV
 
 # Alternatively using Homebrew
 brew install fastlane
modified   docs/includes/use-a-gemfile.md
@@ -6,6 +6,8 @@ source "https://rubygems.org"
 
 gem "fastlane"
 ```
+- Run `[sudo] gem install [--user-install] bundler`
+- Run `bundle config set path 'vendor/bundle'`
 - Run `[sudo] bundle update` and add both the `./Gemfile` and the `./Gemfile.lock` to version control
 - Every time you run _fastlane_, use `bundle exec fastlane [lane]`
 - On your CI, add `[sudo] bundle install` as your first build step

Implicit there is my local change of the following, because I wondered if we should move the "Use a Gemfile" up as a subsection of "Installing fastlane". But not sure that is really necessary.

modified   docs/getting-started/android/setup.md
@@ -81,15 +81,4 @@ You can find your shell profile at `~/.bashrc`, `~/.bash_profile`, `~/.profile`
 
 ### Use a Gemfile
 
-It is recommended that you use a `Gemfile` to define your dependency on _fastlane_. This will clearly define the used _fastlane_ version, and its dependencies, and will also speed up using _fastlane_.
-
-- Create a `./Gemfile` in the root directory of your project with the content
-```ruby
-source "https://rubygems.org"
-
-gem "fastlane"
-```
-- Run `[sudo] bundle update` and add both the `./Gemfile` and the `./Gemfile.lock` to version control
-- Every time you run _fastlane_, use `bundle exec fastlane [lane]`
-- On your CI, add `[sudo] bundle install` as your first build step
-- To update _fastlane_, just run `[sudo] bundle update fastlane`
+{!docs/includes/use-a-gemfile.md!}
modified   docs/getting-started/ios/setup.md
@@ -47,15 +47,4 @@ You can find your shell profile at `~/.bashrc`, `~/.bash_profile`, `~/.profile`
 
 ### Use a Gemfile
 
-It is recommended that you use a `Gemfile` to define your dependency on _fastlane_. This will clearly define the used _fastlane_ version, and its dependencies, and will also speed up using _fastlane_.
-
-- Create a `./Gemfile` in the root directory of your project with the content
-```ruby
-source "https://rubygems.org"
-
-gem "fastlane"
-```
-- Run `[sudo] bundle update` and add both the `./Gemfile` and the `./Gemfile.lock` to version control
-- Every time you run _fastlane_, use `bundle exec fastlane [lane]`
-- On your CI, add `[sudo] bundle install` as your first build step
-- To update _fastlane_, just run `[sudo] bundle update fastlane`
+{!docs/includes/use-a-gemfile.md!}
new file   docs/includes/use-a-gemfile.md
@@ -0,0 +1,12 @@
+It is recommended that you use a `Gemfile` to define your dependency on _fastlane_. This will clearly define the used _fastlane_ version, and its dependencies, and will also speed up using _fastlane_.
+
+- Create a `./Gemfile` in the root directory of your project with the content
+```ruby
+source "https://rubygems.org"
+
+gem "fastlane"
+```
+- Run `[sudo] bundle update` and add both the `./Gemfile` and the `./Gemfile.lock` to version control
+- Every time you run _fastlane_, use `bundle exec fastlane [lane]`
+- On your CI, add `[sudo] bundle install` as your first build step
+- To update _fastlane_, just run `[sudo] bundle update fastlane`
janpio commented

Hm, why the more "clever" version with the optional sudo? I think I like the explicit listing of different options better to be honest as it needs less understanding in users.

bradyt commented

I agree. Avoid the optional sudo near beginning of setup docs? Like this?

modified   docs/includes/installing-fastlane.md
@@ -8,7 +8,7 @@ Install _fastlane_ using
 
 ```sh
 # Using RubyGems
 sudo gem install fastlane -NV

+# Alternatively without sudo
+gem install --user-install fastlane -NV
+
 # Alternatively using Homebrew
 brew install fastlane

I don't know how you prefer the Gemfile section. Do you want to allow optional sudo notation? Or show the alternatives? Do you want to move the Gemfile/bundler approach up as a subsection of installing? Or keep it at end since it's just a bit longer than is desired for a "quickstart" section.

rogerluan commented

This was resolved as part of #1022 💪

Let us know if you still have questions/concerns! 🙏

  • 🎉1