Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
OSSから学んだPR Descriptionの書き方
Search
Fu-ga
January 21, 2023
Programming
4
450
OSSから学んだPR Descriptionの書き方
2023-01-21(Sat) BuriKaigi 2023 で登壇した際の資料です。
Fu-ga
January 21, 2023
Tweet
Share
More Decks by Fu-ga
See All by Fu-ga
初めてのパフォーマンス改善
fugakkbn
18
6.7k
入社数ヶ月のnewbieが 稼働7年超のプロジェクトに 型を導入して見えた世界
fugakkbn
4
4k
オンライン時代のペアプログラミング
fugakkbn
1
1k
Types teaches success, what will we do?
fugakkbn
1
11k
What I can do to get the job smoothly
fugakkbn
0
380
introduction-to-rindokurb
fugakkbn
0
470
fbc-lt-code-review
fugakkbn
0
1.2k
Learn "QUIC" Quickly!
fugakkbn
0
370
タスクの洗い出しという壁 /fjord-lt-slide-fuga
fugakkbn
2
890
Other Decks in Programming
See All in Programming
エンジニア向け採用ピッチ資料
inusan
0
180
Railsアプリケーションと パフォーマンスチューニング ー 秒間5万リクエストの モバイルオーダーシステムを支える事例 ー Rubyセミナー 大阪
falcon8823
4
1k
Select API from Kotlin Coroutine
jmatsu
1
220
PHPでWebSocketサーバーを実装しよう2025
kubotak
0
260
AIと”コードの評価関数”を共有する / Share the "code evaluation function" with AI
euglena1215
1
100
Cursor AI Agentと伴走する アプリケーションの高速リプレイス
daisuketakeda
1
130
Webの外へ飛び出せ NativePHPが切り拓くPHPの未来
takuyakatsusa
2
470
WindowInsetsだってテストしたい
ryunen344
1
230
データの民主化を支える、透明性のあるデータ利活用への挑戦 2025-06-25 Database Engineering Meetup#7
y_ken
0
340
20250704_教育事業におけるアジャイルなデータ基盤構築
hanon52_
5
410
ソフトウェア品質を数字で捉える技術。事業成長を支えるシステム品質の マネジメント
takuya542
1
3k
『自分のデータだけ見せたい!』を叶える──Laravel × Casbin で複雑権限をスッキリ解きほぐす 25 分
akitotsukahara
2
610
Featured
See All Featured
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
233
17k
Fantastic passwords and where to find them - at NoRuKo
philnash
51
3.3k
Creating an realtime collaboration tool: Agile Flush - .NET Oxford
marcduiker
30
2.1k
Large-scale JavaScript Application Architecture
addyosmani
512
110k
Gamification - CAS2011
davidbonilla
81
5.3k
Site-Speed That Sticks
csswizardry
10
680
Become a Pro
speakerdeck
PRO
28
5.4k
Keith and Marios Guide to Fast Websites
keithpitt
411
22k
Side Projects
sachag
455
42k
VelocityConf: Rendering Performance Case Studies
addyosmani
331
24k
Building Flexible Design Systems
yeseniaperezcruz
328
39k
The Cult of Friendly URLs
andyhume
79
6.5k
Transcript
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
my first time at BURIKAIGI! https://connpass-tokyo.s3.amazonaws.com/thumbs/6e/e1/6ee144801b1e5221410445f7e824b669.png
About me About me - 自 己 紹 介 -
ふーが @fugakkbn Ruby / Ruby on Rails 2022.3 エンジニアに転職 前職は警察官👮🏻🚓💨
趣味はダーツ🎯 Kaigi on Rails Organizer ㍿永和システムマネジメント 所属
コミュニティとの 共 生
None
talk about talk about - 今 日 話 す こ
と -
Description of Pull request O N G I T H
U B
None
PR の Description に何を書くか 仕事では「やったこと」とか「変更理由」とかを書いて いるけれど、OSS では何を書くべき? OSS の”お作法”的な何かがあるのだろうか?
思いかえすと… Description の内容が薄くて何の情報もない状態になっ ていたかもしれない いろいろ書いたはいいもののメンテナが求めている(= レビューに有用な)情報ではなかったかもしれない
本日の概要 OSS 活動を通じて、PR Description に何を書くのが良いのか、レビ ュアーの負担を減らせる Description はどういったものか、というの を少しずつ感じ取っています。 自分が書いた
Description をふりかえりながら、これまでに得た気づ きをアウトプットすることで、まだ OSS にコントリビュートしたこと がない方の参考になれば、また、諸先輩方からのフィードバックをい ただける機会になればと思っています。
before that before 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_collection RubyGems(=Rubyライブラリ) の型定義ファイルが集約 されたリポジトリ まだ数が少ない 業務で使っている gem の型定義をしたり、すでに型定義 されているものの修正をしたり
first contribute first contribute - 初 め て の C
o n t r i b u t e -
Pull Request の概要 ActiveDecorator という gem の一部の API に対する型 定義を追加
追加した型定義の正当性を担保するテストを追加 皆さんならどういう Description を書きますか?
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
None
ActiveDecorator gem の型定義を追加しました。
ActiveDecorator gem の型定義を追加しました。 初めて PR を送るので〜云々カンヌン… ただの決意表明
Is it a good one?
Is it a good one?
当時の反省 さすがに情報がなさすぎる感じがするので次はもう少し 情報を書き足してみよう 仕事でも「なぜこうするのか」ということを書いている ので、そういうことを書くのがよさそう!
None
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
None
とあるメソッドではblock が必須と型定義されて いて、block なしで呼び出すとエラーが出ます
とあるメソッドではblock が必須と型定義されて いて、block なしで呼び出すとエラーが出ます 実際にはblock なしで呼び出せるものなので、型定 義もblock をオプションとする変更です。
とあるメソッドではblock が必須と型定義されて いて、block なしで呼び出すとエラーが出ます 実際にはblock なしで呼び出せるものなので、型定 義もblock をオプションとする変更です。 Why Why
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
None
やりたいことは先ほどの例と一緒
やりたいことは先ほどの例と一緒 再現コード 再現コード
やりたいことは先ほどの例と一緒 再現コード 再現コード エラーの内容 エラーの内容
やりたいことは先ほどの例と一緒 再現コード 再現コード エラーの内容 エラーの内容 Why Why
getting a little better 少 し ず つ 良 く
な っ て い る ・ ・ ?
慢心鼻を弾かる
大きな失敗 gem_rbs_collection へのコントリビュートへの要領を掴み、PR を 送ることへの ”馴れ” から大きな失敗をしたのがこのタイミングでし た。 紹介するのも憚られるものですが、ここから学ぶことが多かったので 紹介します。
worst description worst description - 最 低 の D e
s c r i p t i o n -
Pull Request の概要 ActiveRecord という gem のとある API の型定義が自 動生成されたもののままで、引数や戻り値の型が
undefined になっていた undefined のものを(調査した上で)正しい型定義に修 正した
主要な API だから詳しく書かなくてもメンテナはわかるだろう
主要な API だから詳しく書かなくてもメンテナはわかるだろう 単純な型修正だしコードだけでも伝わるだろう
主要な API だから詳しく書かなくてもメンテナはわかるだろう 単純な型修正だしコードだけでも伝わるだろう 自分が調べた内容なんてメンテナは知っているだろう
None
count メソッドの型定義を追加しました また、block を受け付けるようにしました
on twitter T w i t t e r で
見 か け た も の
もらった PR のために調査時間を消費しま くるのが割と厳しい。マージして良いと思 えるように Description でちゃんと説明し てほしい。
業務以上に前提が共有されていない状態な ので「こう変えました!」だけ言われても 困っちゃう。背景の説明により時間をかけ てほしい。
当時の心境
当時の心境 そうは言っても何を書けばいいか 誰からも教わってないし…
当時の心境 そうは言っても何を書けばいいか 誰からも教わってないし… わからないなりに 頑張って書いているのに!
当時の心境 そうは言っても何を書けばいいか 誰からも教わってないし… わからないなりに 頑張って書いているのに! 書いてほしい内容があるなら templateなり使えばいいのでは?
怒り 悲しみ
怒り 悲しみ モチベーション低下 モチベーション低下
しばらくcommitできない日々 「面倒な PR が来た」と思われるの嫌だな 自分の PR がどう思われているのか考えるのが怖い 下手な Description を世界に晒すのが恥ずかしい
None
b y @ k a k u t a n
i - s a n https://speakerdeck.com/kakutani/agile-manifesto-decade?slide=76
K A I Z E N ふ り か え
っ て の 改 善 案
count メソッドの型定義を追加しました また、block を受け付けるようにしました
count メソッドの型定義を追加しました また、block を受け付けるようにしました やったことしか書いていない
業務以上に前提が共有されていない状態な ので「こう変えました!」だけ言われても 困っちゃう。背景の説明により時間をかけ てほしい。
業務以上に前提が共有されていない状態な ので「こう変えました!」だけ言われても 困っちゃう。背景の説明により時間をかけ てほしい。 前提が共有されていない 背景の説明
調査した内容は書く 暗黙の前提は伝わらない 調査結果を共有することでにかかる調査メンテナの負担 を減らせるかもしれない
正当性を担保する根拠を示す 特に ”修正” の場合は重要 現状がなぜ誤りだと言えるのか、修正したものがなぜ正 しいと言えるのか
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
None
ブロックを受け取れるようにする
ブロックを受け取れるようにする エラーの内容 エラーの内容
ブロックを受け取れるようにする エラーの内容 エラーの内容 修正が正しいことを 修正が正しいことを 示すサンプルコード 示すサンプルコード
ブロックを受け取れるようにする エラーの内容 エラーの内容 修正が正しいことを 修正が正しいことを 示すサンプルコード 示すサンプルコード 修正が正しいことを 修正が正しいことを 示すドキュメント
示すドキュメント
ブロックを受け取れるようにする エラーの内容 エラーの内容 修正が正しいことを 修正が正しいことを 示すサンプルコード 示すサンプルコード 修正が正しいことを 修正が正しいことを 示すドキュメント
示すドキュメント
ブロックを受け取れるようにする エラーの内容 エラーの内容 修正が正しいことを 修正が正しいことを 示すサンプルコード 示すサンプルコード 修正が正しいことを 修正が正しいことを 示すドキュメント
示すドキュメント 根拠
ブロックを受け取れるようにする エラーの内容 エラーの内容 修正が正しいことを 修正が正しいことを 示すサンプルコード 示すサンプルコード 修正が正しいことを 修正が正しいことを 示すドキュメント
示すドキュメント 調査内容 根拠
主要な API だから詳しく書かなくてもメンテナはわかるだろう 単純な型修正だしコードだけでも伝わるだろう 自分が調べた内容なんてメンテナは知っているだろう
主要な API だから詳しく書かなくてもメンテナはわかるだろう 単純な型修正だしコードだけでも伝わるだろう 自分が調べた内容なんてメンテナは知っているだろう
”だろう” 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 work scale out to work - 業
務 へ の 横 展 開 -
Kata を修得すると 仕事でも同じ考え方を共有できると思う OSS よりもコンテキストが共有されている部分は多いか もしれないが、情報が多くて困るほどのことにはならな い(経験上)
なんぼあってもいいですからね
まとめ メンテナ(レビュワー)の立場にたって「どんな情報が あるとレビューしやすいか」を考える ”コードにしたものとコードにしなかったことがプログラ ミング” 先人たちの歴史を活用して ”形” を修得する
” ”愚者は経験に学び、 愚者は経験に学び、 賢者は 賢者は歴史 歴史に学ぶ に学ぶ オットー・フォン・ビスマルク オットー・フォン・ビスマルク