Clearer default gemfile (rails#43212)

* More succinct Gemfile comments

* Use double plings

* Separate gems with comments

* Correct separation at the top

* Style

* Use comments for all rails options

* Clearer still

* Clear invocation pointer

* Move tzinfo-data up to all the other gems that are available everywhere

* More succinct

* Better order and spacing

* Add similar read more link style

* No Sass recommendation on minimal

Author: David Heinemeier Hansson

railties/lib/rails/generators/app_base.rb

@@ -158,12 +158,11 @@ def database_gemfile_entry # :doc:
         return [] if options[:skip_active_record]
         gem_name, gem_version = gem_for_database
         GemfileEntry.version gem_name, gem_version,
-                            "Use #{options[:database]} as the database for Active Record"
+          "Use #{options[:database]} as the database for Active Record"
       end
 
       def web_server_gemfile_entry # :doc:
-        comment = "Use Puma as the app server"
-        GemfileEntry.new("puma", "~> 5.0", comment)
+        GemfileEntry.new "puma", "~> 5.0", "Use the Puma web server [https://github.com/puma/puma]"
       end
 
       def include_all_railties? # :doc:
@@ -254,21 +253,21 @@ def version
       def rails_gemfile_entry
         if options.dev?
           [
-            GemfileEntry.path("rails", Rails::Generators::RAILS_DEV_PATH)
+            GemfileEntry.path("rails", Rails::Generators::RAILS_DEV_PATH, "Use local checkout of Rails")
           ]
         elsif options.edge?
           edge_branch = Rails.gem_version.prerelease? ? "main" : [*Rails.gem_version.segments.first(2), "stable"].join("-")
           [
-            GemfileEntry.github("rails", "rails/rails", edge_branch)
+            GemfileEntry.github("rails", "rails/rails", edge_branch, "Use specific branch of Rails")
           ]
         elsif options.main?
           [
-            GemfileEntry.github("rails", "rails/rails", "main")
+            GemfileEntry.github("rails", "rails/rails", "main", "Use main development branch of Rails")
           ]
         else
           [GemfileEntry.version("rails",
                             rails_version_specifier,
-                            "Bundle edge Rails instead: gem 'rails', github: 'rails/rails', branch: 'main'")]
+                            %(Bundle edge Rails instead: gem "rails", github: "rails/rails", branch: "main"))]
         end
       end
 
@@ -287,28 +286,28 @@ def rails_version_specifier(gem_version = Rails.gem_version)
 
       def jbuilder_gemfile_entry
         return [] if options[:skip_jbuilder]
-        comment = "Build JSON APIs with ease. Read more: https://github.com/rails/jbuilder"
+        comment = "Build JSON APIs with ease [https://github.com/rails/jbuilder]"
         GemfileEntry.new "jbuilder", "~> 2.7", comment, {}, options[:api]
       end
 
       def javascript_gemfile_entry
         return [] if options[:skip_javascript]
 
         if options[:javascript] == "importmap"
-          GemfileEntry.version("importmap-rails", ">= 0.3.4", "Manage modern JavaScript using ESM without transpiling or bundling")
+          GemfileEntry.version("importmap-rails", ">= 0.3.4", "Use JavaScript with ESM import maps [https://github.com/rails/importmap-rails]")
         else
-          GemfileEntry.version "jsbundling-rails", "~> 0.1.0", "Bundle and transpile JavaScript with a JavaScript bundler. Read more: https://github.com/rails/jsbundling-rails"
+          GemfileEntry.version "jsbundling-rails", "~> 0.1.0", "Bundle and transpile JavaScript [https://github.com/rails/jsbundling-rails]"
         end
       end
 
       def hotwire_gemfile_entry
         return [] if options[:skip_javascript] || options[:skip_hotwire]
 
         turbo_rails_entry =
-          GemfileEntry.version("turbo-rails", ">= 0.7.11", "Hotwire's SPA-like page accelerator. Read more: https://turbo.hotwired.dev")
+          GemfileEntry.version("turbo-rails", ">= 0.7.11", "Hotwire's SPA-like page accelerator [https://turbo.hotwired.dev]")
 
         stimulus_rails_entry =
-          GemfileEntry.version("stimulus-rails", ">= 0.4.0", "Hotwire's modest JavaScript framework for the HTML you already have. Read more: https://stimulus.hotwired.dev")
+          GemfileEntry.version("stimulus-rails", ">= 0.4.0", "Hotwire's modest JavaScript framework [https://stimulus.hotwired.dev]")
 
         [ turbo_rails_entry, stimulus_rails_entry ]
       end
@@ -321,9 +320,9 @@ def css_gemfile_entry
         return [] unless options[:css]
 
         if !using_node? && options[:css] == "tailwind"
-          GemfileEntry.version("tailwindcss-rails", ">= 0.4.3", "Use Tailwind CSS. See: https://github.com/rails/tailwindcss-rails")
+          GemfileEntry.version("tailwindcss-rails", ">= 0.4.3", "Use Tailwind CSS [https://github.com/rails/tailwindcss-rails]")
         else
-          GemfileEntry.version("cssbundling-rails", ">= 0.1.0", "Bundle and process CSS with Tailwind, PostCSS, or Sass. Read more: https://github.com/rails/cssbundling-rails")
+          GemfileEntry.version("cssbundling-rails", ">= 0.1.0", "Bundle and process CSS [https://github.com/rails/cssbundling-rails]")
         end
       end
 

railties/lib/rails/generators/rails/app/templates/Gemfile.tt

@@ -2,74 +2,66 @@ source "https://rubygems.org"
 git_source(:github) { |repo| "https://github.com/#{repo}.git" }
 
 ruby <%= "\"#{RUBY_VERSION}\"" -%>
-
-<% unless gemfile_entries.first&.comment -%>
-
-<% end -%>
 <% gemfile_entries.each do |gem| -%>
-<% if gem.comment -%>
+<% if gem.comment %>
 
 # <%= gem.comment %>
 <% end -%>
 <%= gem.commented_out ? "# " : "" %>gem "<%= gem.name %>"<%= %(, "#{gem.version}") if gem.version -%>
-<% if gem.options.any? -%>
-, <%= gem.options.map { |k,v|
-  "#{k}: #{v.inspect.gsub('"', '\'')}" }.join(", ") %>
-<% end -%>
-<% end -%>
-<% unless options.skip_sprockets? %>
+<% if gem.options.any? -%>, <%= gem.options.map { |k,v| "#{k}: #{v.inspect}" }.join(", ") %><% end -%>
+<% end %>
+
+# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
+gem "tzinfo-data", platforms: %i[ mingw mswin x64_mingw jruby ]
+
+<% if depend_on_bootsnap? -%>
+# Reduces boot times through caching; required in config/boot.rb
+gem "bootsnap", ">= 1.4.4", require: false
+
+<%- end -%>
+# Use Active Model has_secure_password [https://guides.rubyonrails.org/active_model_basics.html#securepassword]
+# gem "bcrypt", "~> 3.1.7"
+<% unless options.skip_sprockets? || options.minimal? -%>
 
 # Use Sass to process CSS
 # gem "sassc-rails", "~> 2.1"
 <% end -%>
-
-# Use Active Model has_secure_password
-# gem "bcrypt", "~> 3.1.7"
 <% unless skip_active_storage? -%>
 
-# Use Active Storage variant
+# Use Active Storage variants [https://guides.rubyonrails.org/active_storage_overview.html#transforming-images]
 # gem "image_processing", "~> 1.2"
 <% end -%>
-
-<% if depend_on_bootsnap? -%>
-# Reduces boot times through caching; required in config/boot.rb
-gem "bootsnap", ">= 1.4.4", require: false
-
-<%- end -%>
 <%- if options.api? -%>
+
 # Use Rack CORS for handling Cross-Origin Resource Sharing (CORS), making cross-origin AJAX possible
 # gem "rack-cors"
-
 <%- end -%>
 <% if RUBY_ENGINE == "ruby" -%>
+
 group :development, :test do
-  # See https://github.com/ruby/debug for usage
+  # Start debugger with binding.b [https://github.com/ruby/debug]
   gem "debug", ">= 1.0.0", platforms: %i[ mri mingw x64_mingw ]
 end
-
 <% end -%>
+
 group :development do
 <%- unless options.api? || options.skip_dev_gems? -%>
-  # Access an interactive console on exception pages or by calling "console" anywhere in the code.
+  # Use console on exceptions pages [https://github.com/rails/web-console]
   gem "web-console", ">= 4.1.0"
 
-  # Display speed badge on every html page with SQL times and flame graphs.
-  # Note: Interferes with etag cache testing. Can be configured to work on production: https://github.com/MiniProfiler/rack-mini-profiler/blob/master/README.md
+  # Add speed badges [https://github.com/MiniProfiler/rack-mini-profiler]
   # gem "rack-mini-profiler", "~> 2.0"
+
 <%- end -%>
-  # Speed up rails commands in dev on slow machines / big apps. See: https://github.com/rails/spring
+  # Speed up commands on slow machines / big apps [https://github.com/rails/spring]
   # gem "spring"
 end
 
 <%- if depends_on_system_test? -%>
 group :test do
-  # Adds support for Capybara system testing and selenium driver
+  # Use system testing [https://guides.rubyonrails.org/testing.html#system-testing]
   gem "capybara", ">= 3.26"
   gem "selenium-webdriver"
-  # Easy installation and use of web drivers to run system tests with browsers
   gem "webdrivers"
 end
-
-<%- end -%>
-# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
-gem "tzinfo-data", platforms: %i[ mingw mswin x64_mingw jruby ]
+<%- end -%>

railties/lib/rails/generators/rails/plugin/templates/Gemfile.tt

@@ -32,7 +32,7 @@ end
 
 <% end -%>
 <% if RUBY_ENGINE == "ruby" -%>
-# See https://github.com/ruby/debug for usage
+# Start debugger with binding.b -- Read more: https://github.com/ruby/debug
 # gem "debug", ">= 1.0.0", group: %i[ development test ]
 <% end -%>
 <% if RUBY_PLATFORM.match(/bccwin|cygwin|emx|mingw|mswin|wince|java/) -%>