2017年9月27日水曜日

WalBにプルリクしてMagedされた話 #ossgate

[walb-linux/walb-tools] doc: Modify comment about Tutorial (#2)
この記事は何？
  • OSSでパッチを作る時のハウツーを述べました。
  • WalBにGithubでプルリクエストを送りました。
  • 変更内容は瑣末なことですが、改善チャンスを見つけられるかどうかは心持ちが大事なことも多いです。
  • この記事ではプルリクのやり方やパッチの作り方などは紹介していません。









---
WalBがツイッターで少し話題になっていたので、ぼそっとつぶやいたところ中の人に補足されて少し雑談していました。
その中でドキュメントを充実させたい。というような話があり、パーッとさらうような形で読みました。
すごい充実してるしチュートリアルまである。Vagrantで環境作るところまであるじゃーん！なってました。

ただ、そこの目次がTutorial（Japanese)って書いてあるのに、リンク先は英語でした。
最初は途中で英語版作って差し替えたんだなーぐらいにしか思っていなかったのですが、実は日本語のチュートリアルも存在していることをまた別の中の人からのメンションで知りました。

それで、そのことをぼそっとつぶやいたら修正しておきます。と言われてピキーンとなった次第です。
そうです、プルリクチャンスは実は目の前に転がっていたりするものなのです。ちょっとでも良くしようという気持ちがなければ気付かないものです。

どのように変更するか？ですが、今回はJapaneseと書いてあるのが間違いなので削除するだけなので、明瞭です。
次にコミットメッセージをどうするか？を考える必要があります。
１行目はサマリーを短く書く。２行目は空行。３行目はDiscriptionと言って説明書きを書く。というのがGitのお作法です。

しかしながら、それだけでは少し不十分なのです。
コミットメッセージの書き方というのは、プロジェクトによってお作法を持っていることがよくあります。
しかし、それが明文化されていてルールになっていることは、反してあまりありません。
では、どうするか。過去のコミットメッセージをざっと眺めましょう。

眺め方にもちょっとしたコツがあります。git logで全部出して眺めたあとに、git log 変更するファイル　でそのファイルのログだけをたどるのです。変更するファイルの性質によって、変更する内容というのもおおよそ決まってきますから効果的に検討をつけることができる。というわけです。
今回はあまり決まったものはなさそうでした。ただ、接頭語として"doc:" とついていたのでこれに習うことにしました。

これで、もうコミットメッセージは書けそうですね。
しかし、せっかくなのでもう少しだけ一手間かけましょう。

変更の内容に対して、"依存・関係するファイル" を考慮します。
どうゆうことかというと、今回の変更内容を思い出してみて下さい。
なぜ、元のファイルにはJapaneseという文字が入っていたのでしょうか？
考えられることは、最初は日本語へのファイルだったということです。
それならば、その日本語のファイルはどうなったのか？というのは、説明書きにあってもよいのではないでしょうか？
もしくは、日本語のファイルを示すように目次に書き足すのも良いかもしれません。
私は目次は英語だったので、ひとまず前者だけ気をつけました。

Descriptionsには、文字通り説明ですが、何を説明するかというとなぜ変更するのか？といったパッチから読み取りにくい事柄全てです。
たいていプログラムのソースコードにしろ、その変更は何処かに影響を与えて何かを作用したりしますし、その前提となる背景事情というものが存在することが多いです。

あとはプルリクして終了です。

今回はGithub上でしたが、いきなり送りつけることを不快に思うオーナーさんもいるかもしれません。
何か不安事があれば、知ってそうな人やオーナーに見える範囲、メーリングリストなどで質問するのが良いでしょう。

１度経験してるとパーッと抑えるところが分かっているので割りと簡単にできるものです。
しかしながら、勘所を知らないと難しく感じるのもまた事実だと思います。
小さなことでもできることを精度良くやる。というのはOSSを使うから参加する。の一歩だと思いますのでぜひチャンスを見かけたらトライしてみて下さい。
時刻:

0 件のコメント:

コメントを投稿

登録: コメントの投稿 (Atom)