2023-01-21(Sat) BuriKaigi 2023 で登壇した際の資料です。
HOW to writeHOW to writepr descriptionpr descriptionat ossat ossB u r i K a i g i 2 0 2 3
View Slide
my first time atBURIKAIGI!https://connpass-tokyo.s3.amazonaws.com/thumbs/6e/e1/6ee144801b1e5221410445f7e824b669.png
About meAbout me-自 己 紹 介 -
ふーが @fugakkbnRuby / Ruby on Rails2022.3 エンジニアに転職前職は警察官👮🏻🚓💨趣味はダーツ🎯Kaigi on Rails Organizer㍿永和システムマネジメント 所属
コミュニティとの共 生
talk abouttalk about-今 日 話 す こ と -
Description of Pull requestO N G I T H U B
PR の Description に何を書くか仕事では「やったこと」とか「変更理由」とかを書いているけれど、OSS では何を書くべき？OSS の”お作法”的な何かがあるのだろうか？
思いかえすと…Description の内容が薄くて何の情報もない状態になっていたかもしれないいろいろ書いたはいいもののメンテナが求めている（＝レビューに有用な）情報ではなかったかもしれない
本日の概要OSS 活動を通じて、PR Description に何を書くのが良いのか、レビュアーの負担を減らせる Description はどういったものか、というのを少しずつ感じ取っています。自分が書いた Description をふりかえりながら、これまでに得た気づきをアウトプットすることで、まだ OSS にコントリビュートしたことがない方の参考になれば、また、諸先輩方からのフィードバックをいただける機会になればと思っています。
before thatbefore that-本 題 に 入 る 前 に -
いくつか前提がありますここでいう”OSS”についてGitHub 上にリポジトリがありコントリビューターはmain(master) ブランチに向けた Pull Request を開いてメンテナにレビューしてもらうPR が承認されると main にマージされる…という一連の流れを”コントリビュート”と呼称します
gem_rbs_collection" D e f i n i t e l y T y p e d " a s i n T y p e S c r i p t
gem_rbs_collectionRubyGems(=Rubyライブラリ) の型定義ファイルが集約されたリポジトリまだ数が少ない業務で使っている gem の型定義をしたり、すでに型定義されているものの修正をしたり
first contributefirst contribute-初 め て の C o n t r i b u t e -
Pull Request の概要ActiveDecorator という gem の一部の API に対する型定義を追加追加した型定義の正当性を担保するテストを追加皆さんならどういうDescription を書きますか？
ruby/gem_rbs_collection #164P u l l R e q u e s t : A d d R B S f o r A c t i v e D e c o r a t o r g e m
ActiveDecorator gemの型定義を追加しました。
ActiveDecorator gemの型定義を追加しました。初めて PRを送るので〜云々カンヌン…ただの決意表明
Is it a good one?
当時の反省さすがに情報がなさすぎる感じがするので次はもう少し情報を書き足してみよう仕事でも「なぜこうするのか」ということを書いているので、そういうことを書くのがよさそう！
ruby/gem_rbs_collection #165P u l l R e q u e s t : A l l o w o p t i o n a l b l o c k f o r # f i n d _ o r _ c r e a t e _ b y
とあるメソッドではblockが必須と型定義されていて、blockなしで呼び出すとエラーが出ます
とあるメソッドではblockが必須と型定義されていて、blockなしで呼び出すとエラーが出ます実際にはblockなしで呼び出せるものなので、型定義もblockをオプションとする変更です。
とあるメソッドではblockが必須と型定義されていて、blockなしで呼び出すとエラーが出ます実際にはblockなしで呼び出せるものなので、型定義もblockをオプションとする変更です。WhyWhy
ruby/gem_rbs_collection #168A l l o w s o m e m e t h o d s o f A c t i v e R e c o r d : : R e l a t i o n t o a c c e p t o p t i o n a l b l o c k a r g u m e n t s
やりたいことは先ほどの例と一緒
やりたいことは先ほどの例と一緒再現コード再現コード
やりたいことは先ほどの例と一緒再現コード再現コードエラーの内容エラーの内容
やりたいことは先ほどの例と一緒再現コード再現コードエラーの内容エラーの内容WhyWhy
getting a little better少 し ず つ 良 く な っ て い る ・ ・ ？
慢心鼻を弾かる
大きな失敗gem_rbs_collection へのコントリビュートへの要領を掴み、PR を送ることへの ”馴れ” から大きな失敗をしたのがこのタイミングでした。紹介するのも憚られるものですが、ここから学ぶことが多かったので紹介します。
worst descriptionworst description-最 低 の D e s c r i p t i o n -
Pull Request の概要ActiveRecord という gem のとある API の型定義が自動生成されたもののままで、引数や戻り値の型がundefined になっていたundefined のものを（調査した上で）正しい型定義に修正した
主要な API だから詳しく書かなくてもメンテナはわかるだろう
主要な API だから詳しく書かなくてもメンテナはわかるだろう単純な型修正だしコードだけでも伝わるだろう
主要な API だから詳しく書かなくてもメンテナはわかるだろう単純な型修正だしコードだけでも伝わるだろう自分が調べた内容なんてメンテナは知っているだろう
countメソッドの型定義を追加しましたまた、blockを受け付けるようにしました
on twitterT w i t t e rで 見 か け た も の
もらった PRのために調査時間を消費しまくるのが割と厳しい。マージして良いと思えるように Descriptionでちゃんと説明してほしい。
業務以上に前提が共有されていない状態なので「こう変えました！」だけ言われても困っちゃう。背景の説明により時間をかけてほしい。
当時の心境
当時の心境そうは言っても何を書けばいいか誰からも教わってないし…
当時の心境そうは言っても何を書けばいいか誰からも教わってないし…わからないなりに頑張って書いているのに！
当時の心境そうは言っても何を書けばいいか誰からも教わってないし…わからないなりに頑張って書いているのに！書いてほしい内容があるならtemplateなり使えばいいのでは？
怒り悲しみ
怒り悲しみモチベーション低下モチベーション低下
しばらくcommitできない日々「面倒な PR が来た」と思われるの嫌だな自分の PR がどう思われているのか考えるのが怖い下手な Description を世界に晒すのが恥ずかしい
b y @ k a k u t a n i - s a nhttps://speakerdeck.com/kakutani/agile-manifesto-decade?slide=76
K A I Z E Nふ り か え っ て の 改 善 案
countメソッドの型定義を追加しましたまた、blockを受け付けるようにしましたやったことしか書いていない
業務以上に前提が共有されていない状態なので「こう変えました！」だけ言われても困っちゃう。背景の説明により時間をかけてほしい。前提が共有されていない背景の説明
調査した内容は書く暗黙の前提は伝わらない調査結果を共有することでにかかる調査メンテナの負担を減らせるかもしれない
正当性を担保する根拠を示す特に ”修正” の場合は重要現状がなぜ誤りだと言えるのか、修正したものがなぜ正しいと言えるのか
ruby/gem_rbs_collection #226F i x A c t i v e R e c o r d : : B a s e . a f t e r _ c r e a t e t o b e c a l l a b l e w i t h b l o c k
ブロックを受け取れるようにする
ブロックを受け取れるようにするエラーの内容エラーの内容
ブロックを受け取れるようにするエラーの内容エラーの内容修正が正しいことを修正が正しいことを示すサンプルコード示すサンプルコード
ブロックを受け取れるようにするエラーの内容エラーの内容修正が正しいことを修正が正しいことを示すサンプルコード示すサンプルコード修正が正しいことを修正が正しいことを示すドキュメント示すドキュメント
ブロックを受け取れるようにするエラーの内容エラーの内容修正が正しいことを修正が正しいことを示すサンプルコード示すサンプルコード修正が正しいことを修正が正しいことを示すドキュメント示すドキュメント根拠
ブロックを受け取れるようにするエラーの内容エラーの内容修正が正しいことを修正が正しいことを示すサンプルコード示すサンプルコード修正が正しいことを修正が正しいことを示すドキュメント示すドキュメント調査内容根拠
”だろう” is Bad”かもしれない” is Better
Make the "Kata"Make the "Kata"-自 分 の ”カ タ ”を 作 る -
Kata is ...武道などで規範となる方式カタにはまったものではないし、そうではあってはならないという意味で「型」ではなく「形」PR Description も「形」を掴む必要がある
https://github.com/ruby/gem_rbs_collection/graphs/contributors
https://contributors.rubyonrails.org/contributors/in-time-window/this-year
Kata を学ぶには先人がのこした歴史から学ぶのが早くて効率的（ただし選球眼は必要）Contributors などが参考になる余談ですが、英語の言い回しなんかも学びやすい
scale out to workscale out to work-業 務 へ の 横 展 開 -
Kata を修得すると仕事でも同じ考え方を共有できると思うOSS よりもコンテキストが共有されている部分は多いかもしれないが、情報が多くて困るほどのことにはならない（経験上）
なんぼあってもいいですからね
まとめメンテナ（レビュワー）の立場にたって「どんな情報があるとレビューしやすいか」を考える”コードにしたものとコードにしなかったことがプログラミング”先人たちの歴史を活用して ”形” を修得する
””愚者は経験に学び、愚者は経験に学び、賢者は賢者は歴史歴史に学ぶに学ぶオットー・フォン・ビスマルクオットー・フォン・ビスマルク
fugakkbn
usamik26
okuramasafumi
utgwkk
iwasiman
kageshiron
fendo181
yamish123
mikobaaaaa0920
andrewradev
mackee
punchdrunker
tanoku
stephaniewalter
maltzj
paigeccino
3n
jacobian
reverentgeek
geoffreycrofte
sachag
ddemaree
jmmastey
lara