kakudooo docs

Gemfile Style Guide

よいGemfileの書き方について。調べた内容をまとめてみることにする。

基本は、RuboCopのBundlerを参考にした。

• RuboCopのデフォルトで有効になっているものをLEVEL 1
• RuboCopのデフォルトで無効になっているが項目としては存在するものをLEVEL 2
• より発展的なものや事例から得たルールについては、その他

にそれぞれ分類した。

LEVEL 1

RuboCop設定において、デフォルトで有効になっている項目、当たり前なものも多い

source ‘https://rubygems.org’ を指定する

https://docs.rubocop.org/rubocop/cops_bundler.html#bundlerinsecureprotocolsource

• 強く推奨(strongly recommended)されている項目
• セキュアなプロトコルではないことによる、中間者攻撃対策
  • 中間サーバーから意図しないgemに置き換えられたりする可能性もある

# bad
source :gemcutter
source :rubygems
source :rubyforge

# good
source 'https://rubygems.org'

gemを重複して書かない

https://docs.rubocop.org/rubocop/cops_bundler.html#bundlerduplicatedgem

# bad
gem 'rubocop'
gem 'rubocop'

# bad
group :development do
  gem 'rubocop'
end

group :test do
  gem 'rubocop'
end

# good
group :development, :test do
  gem 'rubocop'
end

# good
gem 'rubocop', groups: [:development, :test]

# good
# 条件分岐で書くのはOK
if Dir.exist?(local)
  gem 'rubocop', path: local
elsif ENV['RUBOCOP_VERSION'] == 'master'
  gem 'rubocop', git: 'https://github.com/rubocop/rubocop.git'
else
  gem 'rubocop', '~> 0.90.0'
end

gemのgroupやgroupのセットは重複して書かない

https://docs.rubocop.org/rubocop/cops_bundler.html#bundlerduplicatedgroup

# bad
group :development do
  gem 'rubocop'
end

group :development do
  gem 'rubocop-rails'
end

# bad
group :development, :test do
  gem 'rubocop'
end

group :test, :development do
  gem 'rspec'
end

# good
group :development do
  gem 'rubocop'
end

group :development, :test do
  gem 'rspec'
end

# good
gem 'rubocop', groups: [:development, :test]
gem 'rspec', groups: [:development, :test]

設定に基づいてファイルが作成されている

https://docs.rubocop.org/rubocop/cops_bundler.html#bundlergemfilename

設定に応じて

• GemfileとGemfile.lock
• gems.rbとgems.locked

のいずれかの組み合わせになっていること

gemはグループ内でアルファベット順に並べる

https://docs.rubocop.org/rubocop/cops_bundler.html#bundlerorderedgems

# bad
gem 'rubocop'
gem 'rspec'

# good
gem 'rspec'
gem 'rubocop'

# good
gem 'rubocop'

gem 'rspec'

LEVEL 2

RuboCopの設定において、デフォルトで無効になっている任意の項目

各gemにコメントを書く

https://docs.rubocop.org/rubocop/cops_bundler.html#bundlergemcomment

OnlyForで特定のパラメータの場合だけ、コメントを強制することも可能

# bad
gem 'foo'

# good
# Helpers for the foo things.
gem 'foo'

gemのバージョンやコミットの参照が指定されている

https://docs.rubocop.org/rubocop/cops_bundler.html#bundlergemversion

デフォルトはversion指定が強制される。 設定でversion指定なしを強制することも可能。

# bad
gem 'rubocop'

# good
gem 'rubocop', '~> 1.12'

# good
gem 'rubocop', '>= 1.10.0'

# good
gem 'rubocop', '>= 1.5.0', '< 1.10.0'

# good
gem 'rubocop', branch: 'feature-branch'

# good
gem 'rubocop', ref: '74b5bfbb2c4b6fd6cdbbc7254bd7084b36e0c85b'

# good
gem 'rubocop', tag: 'v1.17.0'

その他

書式

• 順番に依存するGemはファイルの上部に書く
• 順番に依存しないGemはGemのカテゴリ(技術や用途)ごとに名前の辞書順に書く
• 順番に依存しないGemは名前の辞書順に書く
• groupが必要なものはgroupメソッドを使って、ファイルの下部に書く

• groupも辞書順に書く

• 参考
  • https://r7kamura.com/articles/2017-09-20-gemfile-fd2c0266ba77

Gemの指定方法

• 特別な理由を除いて、Gitリポジトリを指定してGemを取得しない
  • 外部へのビルド依存性とビルド時間の最小化が目的
  • GitLabではlinterがあるらしい
    • https://docs.gitlab.com/ee/development/gemfile.html#no-gems-fetched-from-git-repositories
• バージョンの指定方法(いくつかの流派がありそう)
  • 脆弱性のあった場合の依存の更新>=演算子をなるべく使う
    • 誤ってダウングレードしないため、固定する
    • https://docs.gitlab.com/ee/development/gemfile.html#upgrading-dependencies-because-of-vulnerabilities
  • Gemfileでは、なるべくバージョンを指定しない
    • bundle updateによって、可能な限り最新のgemのバージョンに追従すべきであるため

コメント

• Gemfileでは、追加したgemに関してのコメントを書く
  • 簡単にでよい
    • カテゴリ(技術や用途)でまとめつつ、それぞれのGemに個別にコメントを書くとよさそう
    • 丁寧に書く場合は、概要とGitHubのリンクまで書く
• 脆弱性や依存関係の問題などによって、やむなくバージョンを固定する場合は必ずそれに関してのコメントを書く
  • Bundler/GemCommentのOnlyForを使うことで強制することができる
  • https://pocke.hatenablog.com/entry/2020/10/17/132111

Rails

Railsのセットアップ時に自動で記述されるGemの書き方、指定、コメントはそのままにしておき、その下からルールを適用する

発展版

以下を参考にするとよさそう。

https://r7kamura.com/articles/2024-11-30-gemfile

個人的な方針

上記をもって、自分がGemfileを作成したりメンテナンスする上での方針を書いておく。 随時追記していく予定。

順番に依存しないGemの順序について

a. 技術や用途のまとまりごとに名前の辞書順に書く

• 分類を考える必要があるが、まとまりがあってわかりやすい
• Rubyの習熟度の高いメンバーが揃っている場合や少人数の場合などだとよさそう

例えば、GraphQL関連のGemを書く場合は以下のような順番で記述する

# GraphQL file upload server  
gem 'apollo_upload_server'
# GraphQL
gem 'graphql'
# GraphQL page based pagination  
gem 'graphql-pagination'

b. 名前の辞書順に書く

こっちだと、分類を考える必要がなく迷いにくい

source "https://rubygems.org"

# Fixed order
gem "rails", "5.1.4"

# Alphabetical order
gem "aaa"
gem "bbb", "1.2.3" # https://github.com/bbb/bbb/issues/123
gem "ccc"

Gemfileでは、追加したgemに関してのコメントを書く

簡易ver

# GraphQL  
# GraphQL file upload server  
gem 'apollo_upload_server'  
# GraphQL Ruby  
gem 'graphql'  
# GraphQL page based pagination  
gem 'graphql-pagination'  
  
# Pagination  
# Kaminari  
gem 'kaminari-activerecord'  
  
# Authorization  
# Pundit  
gem 'pundit'  
  
# Google Cloud  
# Google Cloud Storage  
gem 'google-cloud-storage', '~> 1.11', require: false  
  
# HTTP Client  
# Faraday http cache  
gem 'faraday-http-cache'

参考

• https://techracho.bpsinc.jp/hachi8833/2022_11_10/121901
• https://blog.saeloun.com/2022/08/16/understanding_gemfile_and_gemfile_lock/
• https://docs.rubocop.org/rubocop/cops_bundler.html#bundlergemcomment