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

Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

About me About me - 自己紹介 -

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

コミュニティとの共生

Slide 6

Slide 6 text

No content

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

No content

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

No content

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

Is it a good one?

Slide 24

Slide 24 text

Is it a good one?

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

No content

Slide 27

Slide 27 text

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

Slide 28

Slide 28 text

No content

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

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

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

No content

Slide 34

Slide 34 text

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

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

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

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

慢心鼻を弾かる

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

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

Slide 46

Slide 46 text

No content

Slide 47

Slide 47 text

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

Slide 48

Slide 48 text

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

Slide 49

Slide 49 text

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

Slide 50

Slide 50 text

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

Slide 51

Slide 51 text

当時の心境

Slide 52

Slide 52 text

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

Slide 53

Slide 53 text

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

Slide 54

Slide 54 text

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

Slide 55

Slide 55 text

怒り悲しみ

Slide 56

Slide 56 text

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

Slide 57

Slide 57 text

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

Slide 58

Slide 58 text

No content

Slide 59

Slide 59 text

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

Slide 60

Slide 60 text

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

Slide 61

Slide 61 text

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

Slide 62

Slide 62 text

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

Slide 63

Slide 63 text

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

Slide 64

Slide 64 text

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

Slide 65

Slide 65 text

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

Slide 66

Slide 66 text

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

Slide 67

Slide 67 text

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

Slide 68

Slide 68 text

No content

Slide 69

Slide 69 text

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

Slide 70

Slide 70 text

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

Slide 71

Slide 71 text

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

Slide 72

Slide 72 text

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

Slide 73

Slide 73 text

Slide 74

Slide 74 text

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

Slide 75

Slide 75 text

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

Slide 76

Slide 76 text

Slide 77

Slide 77 text

Slide 78

Slide 78 text

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

Slide 79

Slide 79 text

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

Slide 80

Slide 80 text

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

Slide 81

Slide 81 text

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

Slide 82

Slide 82 text

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

Slide 83

Slide 83 text

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

Slide 84

Slide 84 text

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

Slide 85

Slide 85 text

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

Slide 86

Slide 86 text

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

Slide 87

Slide 87 text

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

Slide 88

Slide 88 text

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