Zenn
🌍

初めてのOSS貢献！ ~誰でもできる30分でドキュメント修正編~

2022/07/22に公開
OSS
documentation
tech

学び(TL;DR)

  • ソースコードとドキュメントは同一レポジトリに。できればコードと同一ファイルに。
  • ドキュメント修正でも、正しいコードの理解が必要。

本編

人生で初めてOSSに作成したPull Requestがマージされました。
ドキュメント修正です。
変更は1行。

PR

https://github.com/chakra-ui/chakra-ui-docs/pull/695

今回OSS貢献に至った一番の理由

それは

会社の個人OKRにOSSコミットがあった。

からです。

OKRとして定義したことで、常に心の片隅に意識がありました。

この意識がなければ今回のドキュメントミスも見送っていたかもしれません。

ついでに...

なお今季の私の個人OKRには

Twitter フォロワー100人

も存在します。

金曜日に記事をあげるので

@_nishisuke

をフォローとこの記事へのいいね❤️

そして記事の公開ツイートの拡散にご協力お願いします🙇

今フォロワー 19 / 100 です😢

流れ

  1. ドキュメントに従っても動かなかった
  2. 15min 動かすために該当コードをgithub上で確認
  3. 1min ドキュメントミスの可能性
  4. 5min Contribute.md 確認
  5. 1min 修正
  6. 5min PR
  7. 1min PR上でやりとり。修正。

ドキュメントに従っても動かなかった

なかなか期待通りに変更が反映されずなんでやねん！
となる経験、みなさんにもあると思います。
スタート地点はいつもの日常です。

const spacing = {
  space: {
    px: '1px',
    0.5: '0.2rem',
    // Snip
  }
}

export const genbaTheme = extendTheme({
  colors,
  styles,
  spacing,
  sizes,
  fontSizes,
})

15min 動かすために該当コードをGitHub上で確認

ローカルはかなりシンプルな状態に保たれていたため、
真っ先にGitHubに該当コードを見に行きました。
エディタやIDEの機能で見ても一緒です。

1min ドキュメントミスの可能性

コードを見てすぐに、引数に渡しているオブジェクトの形
が違いそうと思いました。
雑にそれっぽい形のオブジェクトを渡すことで期待通り動くことを確認しました。

該当ライブラリはTypescriptを使用しているのですが、この辺の型の指定がいまいちだなあと感じました。
コード自体への修正チャンスでしたが、一旦心の隅に追いやりました。

5min Contribute.md 確認

該当ライブラリはコードとドキュメントのレポジトリが別でした。
なのでドキュメント用のレポジトリに飛んで Contribute.md を確認します。

OSS に貢献する場合、貢献方法について指定されてる場合が多いです。

郷に入っては郷に従え

です。

レポジトリをフォークしたり、コミットにプレフィックスをつけるよう書いてありました。

1min 修正

雑にgrepして修正範囲を見つけました。

5min PR

PRを作成し、説明を記述します。

ドキュメント通りやったが動かなかった。

本当はこうじゃないか？みたいなことを英語で書きました。

1min PR上でやりとり。修正。

修正内容はよかったものの、修正方法について返信をもらいました。
正しいことを言っていると感じたため、それに従い修正しました。

今回の貢献意義について

私と同じように該当コードで動かない思いをしてる人がいるかもしれません。

たった1行30分の修正で、誰かの5分を節約できるとしたら

非常にコスパが良いと思いました。

終わりに

該当レポジトリには、他にも間違っているドキュメントが散見されました。
これを機にあなたもドキュメント修正してみてはいかがでしょうか？

Discussion