Merge pull request #3055 from znz/bitclust-version-guard

古い bitclust が使われている場合に rake が案内を出すようにする

Author: znz

Gemfile.lock

@@ -1,19 +1,19 @@
 GIT
   remote: https://github.com/rurema/bitclust.git
-  revision: 1a107cfeb0b934615874c731a35f31ae12706125
+  revision: 247aa751289fe7e88cfd696b92dfc8d31b3ef2eb
   specs:
-    bitclust-core (1.4.0)
+    bitclust-core (1.5.0)
       drb
       json
       nkf
       progressbar (>= 1.9.0, < 2.0)
       rack
       rouge
       webrick
-    bitclust-dev (1.4.0)
-      bitclust-core (= 1.4.0)
-    refe2 (1.4.0)
-      bitclust-core (= 1.4.0)
+    bitclust-dev (1.5.0)
+      bitclust-core (= 1.5.0)
+    refe2 (1.5.0)
+      bitclust-core (= 1.5.0)
 
 GEM
   remote: https://rubygems.org/

Rakefile

@@ -52,10 +52,39 @@ def system(*commands)
   super(*commands)
 end
 
+# Gemfile は BITCLUST_PATH（既定値 ../bitclust）にディレクトリが存在すると
+# そちらの bitclust を優先する。古いチェックアウトが残っていると
+# `cannot load such file -- drb` や `invalid option: --markdowntree` のような
+# 分かりにくいエラーで失敗するので、ビルド前に検査して案内を出す
+# (https://github.com/rurema/bitclust/issues/230)
+REQUIRED_BITCLUST_VERSION = Gem::Version.new("1.5.0")
+def check_bitclust_version!
+  begin
+    require "bitclust/version"
+  rescue LoadError
+    abort "bitclust を読み込めませんでした。bundle install を実行してください。"
+  end
+  version = Gem::Version.new(BitClust::VERSION)
+  return if version >= REQUIRED_BITCLUST_VERSION
+  location = $LOADED_FEATURES.grep(%r{bitclust/version\.rb\z}).first
+  abort <<~MESSAGE
+    古い bitclust (#{version}) が使われています（#{REQUIRED_BITCLUST_VERSION} 以上が必要です）。
+    使用中の bitclust: #{location}
+    doctree の Gemfile は、環境変数 BITCLUST_PATH（既定値 ../bitclust）の
+    ディレクトリが存在するとそちらの bitclust を優先します。過去に clone した
+    古い bitclust が残っている場合は、次のいずれかで解決してから
+    bundle install をやり直してください:
+      * ../bitclust を最新にする (cd ../bitclust && git pull)
+      * ../bitclust を使わないなら、ディレクトリを削除・改名するか、
+        BITCLUST_PATH=/nonexistent のように存在しないパスを指定する
+  MESSAGE
+end
+
 # ソースは manual/ の Markdown ツリー（manual/doc は manual/api から自動で取り込まれる）。
 # 旧 refm/ は移行ウィンドウ中の凍結ソース。旧経路でビルドしたい場合は
 # BITCLUST_SOURCE=refm を指定する。
 def generate_database(version)
+  check_bitclust_version!
   puts "generate database of #{version}"
   db = "/tmp/db-#{version}"
   succeeded = system("bundle", "exec",
@@ -81,6 +110,7 @@ def generate_database(version)
 end
 
 def generate_statichtml(version)
+  check_bitclust_version!
   db = "/tmp/db-#{version}"
   generate_database(version) unless File.exist?(db)
   puts "generate static html of #{version}"

docs/Tutorial.md

@@ -37,6 +37,10 @@ https://github.com/rurema/doctree
 
 "自分のアカウント名/doctree" というリポジトリが作られたことを確認してください。
 
+なお、以前に fork したことがある場合は、自分の fork の master が
+rurema/doctree より古くなっています。fork のページの「Sync fork」ボタンで
+最新に同期してから先へ進んでください。
+
 ## 3. リポジトリを作業ディレクトリへと clone する
 
 以下のコマンドを実行し、現在の開発環境にリポジトリをコピーしてください。
@@ -88,6 +92,14 @@ doctree リポジトリで `bundle install` すれば入ります。
 $ bundle install
 ```
 
+なお、doctree の `Gemfile` は、隣のディレクトリ（環境変数 `BITCLUST_PATH`、
+既定値 `../bitclust`）に bitclust のチェックアウトが存在すると、そちらを
+優先して使います（bitclust 自体を開発する人向けの仕組みです）。過去に
+clone した古い bitclust が残っていると、`cannot load such file -- drb` や
+`invalid option: --markdowntree` のようなエラーでビルドに失敗します。
+その場合は `../bitclust` を最新にする（`git pull`）か、削除してから
+`bundle install` をやり直してください。
+
 typo の修正のような日本語の修正程度であれば以下を行わずとも pull request を送っていただいて問題ありません。
 [ReferenceManualFormatDigest](ReferenceManualFormatDigest.md) にあるような書式も修正の対象となる場合はプレビューで確認後に pull request を送っていただけるとありがたいです。