OSS Gateワークショップ 2016-06-11: MKenta: td-client: 作業ログ about workshop

[miyachik]

対象 https://github.com/treasure-data/td-client-ruby
README(Getting Started)読みながらinstallする gem install td-client

[miyachik]

bundleで入れようとしたらgem installだった(勝手にハマった)
run in your console とか書くと親切かも

[miyachik]

Configuration読みながらやってるけど実際にコピペですぐに使えない書き方されてるの若干不親切な感じがする
実際にインスタンスを生成する一文があればわかりやすかった。

[miyachik]

TreasuredataからAPI key取ってくる、公式のなんだし公式のAPI取ってこれるURLをREADMEに書くと便利

[miyachik]

Getting Started見ながらやっても想像で補わなきゃいけない部分があってつらい。
method名しか書かれてなくてクラス名を書かなきゃいけない。
備考: 想像のして間違えた結果

irb(main):002:0> Treasuredata.initalize('API_KEY')
NameError: uninitialized constant Treasuredata
    from (irb):2
    from /Users/kenta.miyachi/.rbenv/versions/2.2.3/bin/irb:11:in `<main>'

[miyachik]

実行環境:

[kenta.miyachi]% ruby -v                                                                                                 [~/OSSWS]
ruby 2.2.3p173 (2015-08-18 revision 51636) [x86_64-darwin15]
[kenta.miyachi]% gem -v                                                                                                  [~/OSSWS]
2.4.5.1

実際にこのverをgemがサポートしていたかを確認するべき

[miyachik]

githubのdescriptionに公式ドキュメントへのlink貼るならREADMEにも貼れば便利なのに

[miyachik]

明らかに td に依存してるのにユーザーにそれをわかってる前提でREADME書かれてる。

[miyachik]

td-client の説明見てるのに公式のドキュメント見たら td の話し始めた。

[miyachik]

それぞれの役割とかをREADMEなり公式ドキュメントやらに書いておくとわかりやすい

[miyachik]

公式ドキュメントにはクラス名とか詳しく書かれてるから別にtd-clientのREADMEにも書いておけば便利っぽい

[miyachik]

ドキュメント通りやってたらエラー

irb(main):012:0> cln.databases.each { |db|
irb(main):013:1*   db.tables.each { |tbl|
irb(main):014:2*     p tbl.db_name
irb(main):015:2>     p tbl.table_name
irb(main):016:2>     p tbl.count
irb(main):017:2>   }
irb(main):018:1> }
TreasureData::AuthError: List databases failed: Failed to Login
    from /Users/kenta.miyachi/.rbenv/versions/2.2.3/lib/ruby/gems/2.2.0/gems/td-client-0.8.81/lib/td/client/api.rb:640:in `raise_error'
    from /Users/kenta.miyachi/.rbenv/versions/2.2.3/lib/ruby/gems/2.2.0/gems/td-client-0.8.81/lib/td/client/api/database.rb:12:in `list_databases'
    from /Users/kenta.miyachi/.rbenv/versions/2.2.3/lib/ruby/gems/2.2.0/gems/td-client-0.8.81/lib/td/client.rb:73:in `databases'
    from (irb):12
    from /Users/kenta.miyachi/.rbenv/versions/2.2.3/bin/irb:11:in `<main>'

ログイン失敗した、ってのはわかったけどなぜ失敗したかはわからない。
他のライブラリだともっと詳細にでる。

[miyachik]

Failed to Login なのでインスタンス生成時に何かコケてるっぽいけどAPIKeyは合ってる。
今回はYBIを通してTreasuredataを使ってるのでそれが原因っぽい。

 @host="api.treasure-data.com",

[miyachik]

td-client の方にはAPI endpoint の設定方法が書いてあった。今までtdの公式ドキュメントを呼んでたので流れがめんどくさい td-clientのREADME -> tdのドキュメント -> td-clientのREADME って戻ってきた

[miyachik]

#56 (comment) で書いたAPI Keyを取得するURLはYBIのAPI Keyを取得するURLなので環境によって違うっぽい。defaultのendpointごとのAPI Key取得URLをREADMEには書くべき。

[miyachik]

opts.merge({:endpoint => "https://api-alternate.treasuredata.com"}でendpoint設定できるよ！ってREADMEに書かれてるけどどこのmethodなのかわかりづらい
察しようとしたけど無理だった

irb(main):020:0* opts.merge({:endpoint => "https://api-alternate.treasuredata.com"})
NameError: undefined local variable or method `opts' for main:Object
    from (irb):20
    from /Users/kenta.miyachi/.rbenv/versions/2.2.3/bin/irb:11:in `<main>'
irb(main):021:0> cln.
irb(main):022:0* cln.opts.merge({:endpoint => "https://api-alternate.treasuredata.com"})
NoMethodError: undefined method `cln' for #<TreasureData::Client:0x007f9e8c4b8750>
    from (irb):22
    from /Users/kenta.miyachi/.rbenv/versions/2.2.3/bin/irb:11:in `<main>'
irb(main):023:0> cln.merge({:endpoint => "https://api-alternate.treasuredata.com"})
NoMethodError: undefined method `merge' for #<TreasureData::Client:0x007f9e8c4b8750>
    from (irb):23
    from /Users/kenta.miyachi/.rbenv/versions/2.2.3/bin/irb:11:in `<main>'

[miyachik]

環境変数でも設定できるっぽいのでそっちでやる...

[miyachik]

Running Testってよりかは実際にtd-clintでコードを書いた時に、specファイルを書くときに有用なgemの話なので若干README不親切

[miyachik]

作業と感想をセットでメモする

[miyachik]

READMEの各順番がおかしい。先にどんなoptがあるのかを明確に書けばわかりやすいっぽい。

ops = Hash.new
ops.merge 
initalize (key, ops)

で書ける?

[miyachik]

ybiのendpointはこっち http://ybi.jp-east.idcfcloud.com
opsにhashでendpoint埋め込んでインスタンス生成する

[miyachik]

いけた。

opts = Hash.new
opts = opts.merge({:endpoint => "http://ybi.jp-east.idcfcloud.com"})
cln = TreasureData::Client.new('API_KEY',opts)

[miyachik]

不満点

• READMEの順番が不親切
• インスタンス生成時( initialize(apikey, opts={}) (constructor) )にoptsの書き方がないのでそれを追記したい
• 具体的には #56 (comment) っぽく

[miyachik]

rdocをmdに書き換える...?

[miyachik]

READMEがrdocでつらい問題

[miyachik]

https://github.com/kirkbowers/rdoc2md

[miyachik]

rdoc2mdでREADME.md化

[miyachik]

forkしてbranch切ってREADME.rdocを変換した。PR書く。

[miyachik]

Convert README.rdoc to Markdown using rdoc2md

[miyachik]

rdocからmdに変換する理由

[miyachik]

markdownだったら別のドキュメントを書き換えてやるっていう気持ちを伝える

[miyachik]

それをPRのコメントに書くとよりmergeされやすい。

[miyachik]

その後にどこを書き換えようとしているのかを伝えると尚良。

[miyachik]

ドキュメントが壊れていないかをURLなどを貼って確認する/させる。
本家
fork先

[miyachik]

リンクより画像を貼っておくと吉

[miyachik]

• commitするようなOSSの管理者は忙しいのでそれを考慮したPRを書く。

[miyachik]

convertしたmarkdownと本家rdocで差がないかなーって見てたらそもそも本家のrdoc記法に漏れがあるのを見つけた
https://github.com/treasure-data/td-client-ruby#additional-user-agents

[miyachik]

向こうがmdにしたくないなら#56 (comment) のPRを送れば良い

[miyachik]

ちゃんと変換できてるのを確認したから今度こそPR書く

[miyachik]

他の人がplease, review it.って語尾につけてるの結構いいかも、そこまで必須のPRではないし、作者が好き好んでrdocを書いている可能性もあるし

[miyachik]

PR出しました 🎉

[kou]

お疲れさまでした！