Upgrade to Pro — share decks privately, control downloads, hide ads and more …

OSSから学んだPR Descriptionの書き方

Fu-ga
January 21, 2023

OSSから学んだPR Descriptionの書き方

2023-01-21(Sat) BuriKaigi 2023 で登壇した際の資料です。

Fu-ga

January 21, 2023
Tweet

More Decks by Fu-ga

Other Decks in Programming

Transcript

  1. HOW to write
    HOW to write
    pr description
    pr description
    at oss
    at oss
    B u r i K a i g i 2 0 2 3

    View Slide

  2. my first time at
    BURIKAIGI!
    https://connpass-tokyo.s3.amazonaws.com/thumbs/6e/e1/6ee144801b1e5221410445f7e824b669.png

    View Slide

  3. About me
    About me
    -
    自 己 紹 介 -

    View Slide

  4. ふーが @fugakkbn
    Ruby / Ruby on Rails
    2022.3 エンジニアに転職
    前職は警察官👮🏻🚓💨
    趣味はダーツ🎯
    Kaigi on Rails Organizer
    ㍿永和システムマネジメント 所属

    View Slide

  5. コミュニティとの
    共 生

    View Slide

  6. View Slide

  7. talk about
    talk about
    -
    今 日 話 す こ と -

    View Slide

  8. Description of Pull request
    O N G I T H U B

    View Slide

  9. View Slide

  10. PR の Description に何を書くか
    仕事では「やったこと」とか「変更理由」とかを書いて
    いるけれど、OSS では何を書くべき?
    OSS の”お作法”的な何かがあるのだろうか?

    View Slide

  11. 思いかえすと…
    Description の内容が薄くて何の情報もない状態になっ
    ていたかもしれない
    いろいろ書いたはいいもののメンテナが求めている(=
    レビューに有用な)情報ではなかったかもしれない

    View Slide

  12. 本日の概要
    OSS 活動を通じて、PR Description に何を書くのが良いのか、レビ
    ュアーの負担を減らせる Description はどういったものか、というの
    を少しずつ感じ取っています。
    自分が書いた Description をふりかえりながら、これまでに得た気づ
    きをアウトプットすることで、まだ OSS にコントリビュートしたこと
    がない方の参考になれば、また、諸先輩方からのフィードバックをい
    ただける機会になればと思っています。

    View Slide

  13. before that
    before that
    -
    本 題 に 入 る 前 に -

    View Slide

  14. いくつか前提があります
    ここでいう”OSS”について
    GitHub 上にリポジトリがありコントリビューターは
    main(master) ブランチに向けた Pull Request を開い
    てメンテナにレビューしてもらう
    PR が承認されると main にマージされる
    …という一連の流れを”コントリビュート”と呼称します

    View Slide

  15. 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

    View Slide

  16. gem_rbs_collection
    RubyGems(=Rubyライブラリ) の型定義ファイルが集約
    されたリポジトリ
    まだ数が少ない
    業務で使っている gem の型定義をしたり、すでに型定義
    されているものの修正をしたり

    View Slide

  17. first contribute
    first contribute
    -
    初 め て の C o n t r i b u t e -

    View Slide

  18. Pull Request の概要
    ActiveDecorator という gem の一部の API に対する型
    定義を追加
    追加した型定義の正当性を担保するテストを追加
    皆さんならどういう
    Description を書きますか?

    View Slide

  19. ruby/gem_rbs_collection #164
    P 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

    View Slide

  20. View Slide

  21. ActiveDecorator gem
    の型定義を追加しました。

    View Slide

  22. ActiveDecorator gem
    の型定義を追加しました。
    初めて PR
    を送るので〜云々カンヌン…
    ただの決意表明

    View Slide

  23. Is it a good one?

    View Slide

  24. Is it a good one?

    View Slide

  25. 当時の反省
    さすがに情報がなさすぎる感じがするので次はもう少し
    情報を書き足してみよう
    仕事でも「なぜこうするのか」ということを書いている
    ので、そういうことを書くのがよさそう!

    View Slide

  26. View Slide

  27. ruby/gem_rbs_collection #165
    P 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

    View Slide

  28. View Slide

  29. とあるメソッドではblock
    が必須と型定義されて
    いて、block
    なしで呼び出すとエラーが出ます

    View Slide

  30. とあるメソッドではblock
    が必須と型定義されて
    いて、block
    なしで呼び出すとエラーが出ます
    実際にはblock
    なしで呼び出せるものなので、型定
    義もblock
    をオプションとする変更です。

    View Slide

  31. とあるメソッドではblock
    が必須と型定義されて
    いて、block
    なしで呼び出すとエラーが出ます
    実際にはblock
    なしで呼び出せるものなので、型定
    義もblock
    をオプションとする変更です。
    Why
    Why

    View Slide

  32. ruby/gem_rbs_collection #168
    A 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

    View Slide

  33. View Slide

  34. やりたいことは先ほどの例と一緒

    View Slide

  35. やりたいことは先ほどの例と一緒
    再現コード
    再現コード

    View Slide

  36. やりたいことは先ほどの例と一緒
    再現コード
    再現コード
    エラーの内容
    エラーの内容

    View Slide

  37. やりたいことは先ほどの例と一緒
    再現コード
    再現コード
    エラーの内容
    エラーの内容
    Why
    Why

    View Slide

  38. getting a little better
    少 し ず つ 良 く な っ て い る ・ ・ ?

    View Slide

  39. 慢心鼻を弾かる

    View Slide

  40. 大きな失敗
    gem_rbs_collection へのコントリビュートへの要領を掴み、PR を
    送ることへの ”馴れ” から大きな失敗をしたのがこのタイミングでし
    た。
    紹介するのも憚られるものですが、ここから学ぶことが多かったので
    紹介します。

    View Slide

  41. worst description
    worst description
    -
    最 低 の D e s c r i p t i o n -

    View Slide

  42. Pull Request の概要
    ActiveRecord という gem のとある API の型定義が自
    動生成されたもののままで、引数や戻り値の型が
    undefined になっていた
    undefined のものを(調査した上で)正しい型定義に修
    正した

    View Slide

  43. 主要な API だから詳しく書かなくてもメンテナはわかるだろう

    View Slide

  44. 主要な API だから詳しく書かなくてもメンテナはわかるだろう
    単純な型修正だしコードだけでも伝わるだろう

    View Slide

  45. 主要な API だから詳しく書かなくてもメンテナはわかるだろう
    単純な型修正だしコードだけでも伝わるだろう
    自分が調べた内容なんてメンテナは知っているだろう

    View Slide

  46. View Slide

  47. count
    メソッドの型定義を追加しました
    また、block
    を受け付けるようにしました

    View Slide

  48. on twitter
    T w i t t e r
    で 見 か け た も の

    View Slide

  49. もらった PR
    のために調査時間を消費しま
    くるのが割と厳しい。マージして良いと思
    えるように Description
    でちゃんと説明し
    てほしい。

    View Slide

  50. 業務以上に前提が共有されていない状態な
    ので「こう変えました!」だけ言われても
    困っちゃう。背景の説明により時間をかけ
    てほしい。

    View Slide

  51. 当時の心境

    View Slide

  52. 当時の心境
    そうは言っても何を書けばいいか
    誰からも教わってないし…

    View Slide

  53. 当時の心境
    そうは言っても何を書けばいいか
    誰からも教わってないし…
    わからないなりに
    頑張って書いているのに!

    View Slide

  54. 当時の心境
    そうは言っても何を書けばいいか
    誰からも教わってないし…
    わからないなりに
    頑張って書いているのに!
    書いてほしい内容があるなら
    templateなり使えばいいのでは?

    View Slide

  55. 怒り
    悲しみ

    View Slide

  56. 怒り
    悲しみ
    モチベーション低下
    モチベーション低下

    View Slide

  57. しばらくcommitできない日々
    「面倒な PR が来た」と思われるの嫌だな
    自分の PR がどう思われているのか考えるのが怖い
    下手な Description を世界に晒すのが恥ずかしい

    View Slide

  58. View Slide

  59. b y @ k a k u t a n i - s a n
    https://speakerdeck.com/kakutani/agile-manifesto-decade?slide=76

    View Slide

  60. K A I Z E N
    ふ り か え っ て の 改 善 案

    View Slide

  61. count
    メソッドの型定義を追加しました
    また、block
    を受け付けるようにしました

    View Slide

  62. count
    メソッドの型定義を追加しました
    また、block
    を受け付けるようにしました
    やったことしか書いていない

    View Slide

  63. 業務以上に前提が共有されていない状態な
    ので「こう変えました!」だけ言われても
    困っちゃう。背景の説明により時間をかけ
    てほしい。

    View Slide

  64. 業務以上に前提が共有されていない状態な
    ので「こう変えました!」だけ言われても
    困っちゃう。背景の説明により時間をかけ
    てほしい。
    前提が共有されていない
    背景の説明

    View Slide

  65. 調査した内容は書く
    暗黙の前提は伝わらない
    調査結果を共有することでにかかる調査メンテナの負担
    を減らせるかもしれない

    View Slide

  66. 正当性を担保する根拠を示す
    特に ”修正” の場合は重要
    現状がなぜ誤りだと言えるのか、修正したものがなぜ正
    しいと言えるのか

    View Slide

  67. ruby/gem_rbs_collection #226
    F 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

    View Slide

  68. View Slide

  69. ブロックを受け取れるようにする

    View Slide

  70. ブロックを受け取れるようにする
    エラーの内容
    エラーの内容

    View Slide

  71. ブロックを受け取れるようにする
    エラーの内容
    エラーの内容
    修正が正しいことを
    修正が正しいことを
    示すサンプルコード
    示すサンプルコード

    View Slide

  72. ブロックを受け取れるようにする
    エラーの内容
    エラーの内容
    修正が正しいことを
    修正が正しいことを
    示すサンプルコード
    示すサンプルコード
    修正が正しいことを
    修正が正しいことを
    示すドキュメント
    示すドキュメント

    View Slide

  73. ブロックを受け取れるようにする
    エラーの内容
    エラーの内容
    修正が正しいことを
    修正が正しいことを
    示すサンプルコード
    示すサンプルコード
    修正が正しいことを
    修正が正しいことを
    示すドキュメント
    示すドキュメント

    View Slide

  74. ブロックを受け取れるようにする
    エラーの内容
    エラーの内容
    修正が正しいことを
    修正が正しいことを
    示すサンプルコード
    示すサンプルコード
    修正が正しいことを
    修正が正しいことを
    示すドキュメント
    示すドキュメント
    根拠

    View Slide

  75. ブロックを受け取れるようにする
    エラーの内容
    エラーの内容
    修正が正しいことを
    修正が正しいことを
    示すサンプルコード
    示すサンプルコード
    修正が正しいことを
    修正が正しいことを
    示すドキュメント
    示すドキュメント
    調査内容
    根拠

    View Slide

  76. 主要な API だから詳しく書かなくてもメンテナはわかるだろう
    単純な型修正だしコードだけでも伝わるだろう
    自分が調べた内容なんてメンテナは知っているだろう

    View Slide

  77. 主要な API だから詳しく書かなくてもメンテナはわかるだろう
    単純な型修正だしコードだけでも伝わるだろう
    自分が調べた内容なんてメンテナは知っているだろう

    View Slide

  78. ”だろう” is Bad
    ”かもしれない” is Better

    View Slide

  79. Make the "Kata"
    Make the "Kata"
    -
    自 分 の ”
    カ タ ”
    を 作 る -

    View Slide

  80. Kata is ...
    武道などで規範となる方式
    カタにはまったものではないし、そうではあってはなら
    ないという意味で「型」ではなく「形」
    PR Description も「形」を掴む必要がある

    View Slide

  81. https://github.com/ruby/gem_rbs_collection/graphs/contributors

    View Slide

  82. https://contributors.rubyonrails.org/contributors/in-time-window/this-year

    View Slide

  83. Kata を学ぶには
    先人がのこした歴史から学ぶのが早くて効率的(ただし
    選球眼は必要)
    Contributors などが参考になる
    余談ですが、英語の言い回しなんかも学びやすい

    View Slide

  84. scale out to work
    scale out to work
    -
    業 務 へ の 横 展 開 -

    View Slide

  85. Kata を修得すると
    仕事でも同じ考え方を共有できると思う
    OSS よりもコンテキストが共有されている部分は多いか
    もしれないが、情報が多くて困るほどのことにはならな
    い(経験上)

    View Slide

  86. なんぼあってもいいですからね

    View Slide

  87. まとめ
    メンテナ(レビュワー)の立場にたって「どんな情報が
    あるとレビューしやすいか」を考える
    ”コードにしたものとコードにしなかったことがプログラ
    ミング”
    先人たちの歴史を活用して ”形” を修得する

    View Slide


  88. ”愚者は経験に学び、
    愚者は経験に学び、
    賢者は
    賢者は歴史
    歴史に学ぶ
    に学ぶ
    オットー・フォン・ビスマルク
    オットー・フォン・ビスマルク

    View Slide