気の向くままに書き綴る

勉強会参加したメモや日々の思ったことのメモ等

良いPull Requestのための10のTips読んだ時のメモ

この記事を先週読んでセコセコ、メモしていたら、日本語の翻訳が出てた。
せっかくの機会なのでGistに貼っていたのもをブログに上げる。


原文 10 tips for better Pull Requests

Yakst - より良いプルリクエストのための10のヒント

良いPull Requestのための10のTips

良いPull Requestを作ることは良いコードを書くこと以上を伴うもの

Pull Requestモデルは、チームで開発する素晴らしい方法であることが判明している(特に分散しているチーム)
もちろんこのモデルはOSS開発だけじゃなくても、エンタープライズでも言える。
2010年位から私は、自身のOSS、顧客のいくつか、また内部のクローズド開発でもPull Requestモデルを行ってきた。

当時、私は多くの偉大なPull Requestを見てきた。
そして、いくつか改善が必要なものがあった。

良いプルリクエストは最適な良いコード以上に含まれている。
ほとんどの場合、一人または多くのレビュアーがいて、
あなたのPull requestがコードベースにフィットするかどうかレビューするんだ。

あなたは良いコードを作るだけじゃなく、レビューアーにあうか考える必要がある。

ここに、あなたのPull requestがより良くなるようにTipsを書いておく。
網羅的ではないけど、良いプルリクエストを作る上で重要な側面だと思ってる。

1. 小さく作る

 小さくすることに集中したPull Requestは取り込まれやすい
 
 大きくなってしまったら、レビューアーと調整して行ったほうが良い。
 レビューは5分毎に刻んで行うことが出来ず、まとまった時間が必要だからだ。
 Pull requestを送るものによるが、
 大体12ファイル以下の変更なら、悪く無いというべきだろう。

2. 一つのことだけをする

単一責任原則のように一つのクラスに一つの責任をもつようにPull requestもそのように一つに絞って出す必要がある。
例えば、あなたが3つの独立した機能をもつPull requestを送った場合に、
AとCは有用であり取り込むべきとなったが、Bには問題があるといったことがしばし起こる。
その場合、Bについて長い議論をし、最終的にPull requestを変更する必要な場合がある。

長い議論の間にもMasterではいくつかCommitされているおり、
既にAとCについては自動でマージできない状況になる。

AとCは既に完璧なものであったにも関わらず結局、宙に浮いている状態である。

そのかわりに、A,B,Cすべてを独立してPull Requestを送った場合、AとCはすぐに取り込まれるだろう。
一つのPullRequestは、一つのことに集中にして行うようにするべきである。

3.  一行の長さを考える

あなたのRullRequestをReviewをする際にレビューアーはDiff toolを使う。
GitHubもStashもWebベースのDiffツールを提供している。
レビューアーは提供されている画面分割されたDiffをみている
それはCodeを画面半分でも読めるようになっている必要がある。

あなたがかいたCodeが横に長かった場合、横スクロールを強制してしまう。

80文字以内にする理由は多くある。リンク先のブログを参照すると良い。

4. フォーマットの変更を避ける

フォーマットを変えたい衝動に駆られるかもしれない。でもそれはやめてほしい。
フォーマットを変更することですべての差分に出てしまう
スペースの差分を出さないオプションをあるが、それをレビューアーが無視するには限界があるんだ。
特にCodeを移動した場合、それを無視することができない。やめてほしい。


スペースの変更がしたい場合、
ファイル内の前後のCodeを移動、フォーマットの変更、スタイルの変更を意図した別のPullrequestにしてほしい
そしてその主旨をコメント書いてほしい。

5. ビルドの確認をする

Pull requestする前に、ローカルでビルドの確認してほしい。
ローカルで動かないのであれば、多分他のマシンでも動かないんだ。

コンパイラの警告は注意してみてほしい。
もしかすると、あなたが気づかないうちにコンパイル警告によって、
レビューアーを妨げるかもしれない。

あまりりの多くのコンパイラの警告がある場合、

あなたのPull requestを拒否するかもしれない。

もしビルド用スクリプトがあれば、試してほしい。
そしてビルドが成功したやつのみPull requestを起こって欲しい。

私の最も多くのOpenSourceのプロジェクトでは、警告をエラーとして扱うビルドスクリプトを作っている。
このようなビルドスクリプトは自動かまたはさまざまな特定なCodeにおいてルールを実装している。

Pull requestを送る前に使ってほしい。
なぜなら、あなたのブランチをマージする前にも利用するからだ。

6. すべてのテストが通ること

テストコードが書かれている場合、
一度すべてテストを実行してほしい。

これは言われる前にするべきだ。
でも、私のところにはひとつまたはそれ以上でテストが通っていないPullrequestが届くんだ。。

7. テストの追加

また、すでにいくつかユニットテストが書かれている場合において、
あなたのPullrequestをテストCodeを追加しよう

私のところにテストがないPullrequestは余り届かないが、
しばしば私は拒否する。

これはハードなルールではない。
テストのカバレッジなしの必要ないろいろな種類のケースが存在する。

でもテストができるものは、テストをするべきなんだ。
そして、あなたは、既存のコードベースのテスト戦略に従うべきなんだ。

8. 理由をドキュメント化する

ドキュメント化したCodeはまれである。
「Codeにあるコメントは謝罪である」というが、
そして、私はコメントより型や変数が良い名前を好む。

まだCodeを書いている時、
私は自明でないかどうかしばしば意思決定をしなければならない。
(特にビジネスロジックの取引を行うときなど)

何を」書いたのかではなく「なぜ」あなたがそうCodeに書いたかを文書化する方法を

私の望ましい順に書いていく。

1. 文書化されたCode

あなたは、自己文書化されたCodeについて、意思決定することができる。
Clean Codeは、文字通りそれについてのHow-toが書かれている。

2. Codeにコメント

もし1が難しい場合、コメントを書こう
少なくとも、Codeと同じ場所にコメントを書こう。
バージョン管理システムが変わってもコメントが消えないようにする。
ここに、私がみたコメントで対処したほうが良い例がある。

internal static string[] GetSegmentsFrom(Uri href)
{
/* The assumption here is that the href argument is always going to
* be a relative URL. So far at least, that's consistent with how
* AtomEventStore works.
* However, the Segments property only works for absolute URLs. */
var fakeBase = new Uri("http://grean.com");
var absoluteHref = new Uri(fakeBase, href);
return absoluteHref.Segments;
}

3. コミットメッセージ

ほとんどのバージョンシステムではコミットを記述する機会がある。
そして多くの人が、必要最低限の記述のみとしている。
しかし、あなたはここに理由を書くことができるんだ。

幾つか、あなたは特定の順序でコミットを行わなければならず、

説明する必要があるかもしれない。
この順序については、Codeのコメントよりコミットメッセージにフィットする。

あなたが同じバージョン管理システムを利用する場合に限り、
あなたのこれらのコミットメッセージは保存される。

しかし、一度実際のCodeからファイルを削除、または、
別のバージョン管理システムを変更した場合メッセージが失われるだろう。

ここにたくさんCommitメッセージを書く必要があった例がある。

ただ、いつもそうであるとは限らない

4.Pull requestのコメント

まれに、上記の方法で適さない状況がある。
GitHubやStashを使っている場合に、Pull request自体にメッセージを追加することができる。
このメッセージは、Codeのコメント、コミットメッセージから更に離れている。
同じバージョン管理システムのホストを使用している限り保存されている。

例えばCodePlexからGitHubに移行すると、
Pull requestのメッセージが失われるだろう。

それでも、場合によってレビュアーに説明する必要があるだろう。
ただし、ソースコード外での説明が必要な場合である。
この方法が適しているがある。

あなたは明らかなものについては説明する必要がない。
しかし、慎重に考えてほしい。

今日のあなたが明らかだとしても、他人が明らかだと限りらない。
まして、三ヶ月後の自分が明らかであるとは限らない

9. 上手く書く

良いコードを書くことだけではなく、良い文も書こう。
これは主観的である。しかし、文とCodeの両方にルールがある。
Codeには正しいルールがある。そうでなければコンパイルはできない。
(インタープリタの場合、落ちるんだ。)

それはPull requestのメッセージ、コミットのメッセージ、Codeのコメントも同じなんだ。

正しいスペル、文法、句読点を使ってほしい。
そうじゃなかったらあなたの文を理解するのは難しい。

そしてあなたのレビュアーも人間なんだ。

10. スラッシングを避ける

レビュアーはPull requestについて、様々な点において指摘をする。
そしてあなたはそれに対して同意するだろう。

これは、Pull Requestのブランチに多くのコメントを残す原因となるだろう。
それ自体には何も問題はありません。

しかしながら、これは不当なスラッシングにつながる。

例えば、
あなたがA,B,C,D,Eの5つのコミットをしたPull requestをして、
レビュアーがBとCのコミットが好きじゃない場合に、Codeを消してと要求してきた。

ほとんどの人はPull requestのブランチをチェックアウトしている。
そして、問題のあるCodeを削除している。
つまり、A,B,C,Dと続き別のコミットFをしている。

なぜ、不要なCodeを追加して、また削除するコミットを追加するのだろうか?

これがスラッシングである。
つまり、無意味なcommitは何も提供しない価値である。

代わりに、該当のコミットを削除して、
強制的に、A,D,EのコミットをPushするようにしよう。
レビュー中のブランチのオーナーはあなた自身なんだ。

他のスラッシングの例として、
古くなってきたPull requestに起きる。(長い議論で起こる)
この場合、Pull requestのブランチのオーナーが定期的にPull requestが通る用にMasterからマージして最新を保つんだ。

もう一度、なぜ私は、すべてのMasterのコミットのMargeの見なければならないのか?
あなたはPull requestのオーナーである。
Pull requestをrebaseして、強制的にPushしてほしい。
そうすれば過去のコミットはすべてキレイになるんだ。

 

※ ここでのスラッシングについて、翻訳ではcommit履歴を言及していました。私自身は、「いちいち無駄なcommitも確認をしなければならない」レビューアーの負荷についてスラッシングと言ってるのかな-と思ってました^^;

 

まとめ

あなたのPull requestは一人または多くの人がレビューする。
レビュアーに仕事をさせてはいけない。
あなたがレビュアーにより仕事をさせた場合、あなたのPull requestはリスクであり拒否されるだろう。

Railsのサーバー運用のShellScriptを作る際に、 書き方や保存先で悩んだ際に参考したサイトとメモ

Railsのサーバー運用のShellScriptを作る際に、
書き方や保存先で悩んだ際に参考したサイトとメモ。
※ ここでのShellScriptは、自動起動とか

 

Rails、かつ、ひと通りドキュメントやSystemの運用保守のノウハウが蓄積されているものに特定してぐぐってみた。
以下3つが引っ掛かったので見てみた。

一番情報が乗っていたものはgitlab
直接アプリケーションに影響しないものをRails_ROOT/lib/supportにおいている。
(なんでsupportは複数形じゃないんだろう?

 

deploy, autorun, logrotate, confとひとつひとつ中身を見ると結構参考になります。

gitlab
supportディレクトリ

lib/
├── support
│   ├── deploy
│   │   └── deploy.sh
│   ├── init.d
│   │   ├── gitlab
│   │   └── gitlab.default.example
│   ├── logrotate
│   │   └── gitlab
│   └── nginx
│   ├── gitlab
│   └── gitlab-ssl

 

spree

特になし。
gem利用で基本的に単体で動かすものではないから(?)

 

Redmine
特になし。
自動起動はPassengerだからというのもあるし、運用系は結構コマンドの紹介が多かった。

JaRedmineInstall - Redmine

wikirsyncとかmysqldumpとか結構そのまま書いている。

 

まとめ

 

世の中でずっと開発されているアプリケーションを見ることで、

  • ここは自分の考慮が足りてなかった

  • 自分たちのSystemでは、❍❍機能が必要だ

と、0から作りより、相対的に良い、悪いの評価ができるので非常に良い。

今年の漢字を考える

あけましておめでとうございます。
koudaiiiです。

 

今年も宜しくお願い致します!

 

毎年、今年の漢字を決めるというのが清水寺で行われてますよね。
Wikipedia 「今年の漢字」

 

過去の漢字とか見て、

あーあれがあった年かー。て思っちゃいますよね。

毎年毎年すげー。

 

同じように、

個人でも今年の漢字を決めよー!みたいなのがこのBlogの主旨です。

 

やることは、簡単で、一文字漢字を決めるだけです。

 

清水寺のとは少し違って一工夫します。

「今年はこういう年にしたいなー。といった抱負」を込めた形で、

年の初めにもう今年の漢字を決めます

それで実際どうだったかをKPTで振り返るみたいなことしてます。


過去エントリーがありました。

 「ええと思ったらやっていく年にしたい。2013年の1文字漢字を考える」

 

今まで年始に決めてやってきたのがこちら。(新人から始めてたんだ。

  • 2010 【粉】 新人。まずは粉にして働く
  • 2011 【荒】 先輩いない。自社ビル引っ越し。とりあえずがんばる。
  • 2012 【基】「おまえなら余裕」と言われるようになることを目標 、チームの大事な存在。インフラの基礎知識を固める
  • 2013 【始】 ええと思ったらやっていく年にしたい。
  • 2014 【創】 創造していく。

 

毎年のふりかえり

特に誰も見せるわけでもなかったし、まあせっかく出し書くかーと始めたものなので結構適当です。でも不思議と思い出せるもので、面白いです。

以下は、2013KPTから2014の取り組みになります。

2013KPT

Keep

新しい分野を断らずにすべて引き受けた
なんとか締め切りを間に合わせている

Problem

奥手な部分が多い。
夜更かしが多い。

Try

ぐいぐい行きたい!
計画性?

 

昨年の2014KPT

Keep

イベントの企画をやりつつも、

自分自身の精進を忘れずやってないことをひたすらやってみました。

実際は形にならず残念でしたが、

企画書から事業計画書、ロードマップ等を含めてガーッと調べて実際に役員の前でプレゼンするといった良い経験でした。

それ以外に、

  • JTF含め外部での発表
  • 初Pull request

 

  • プロジェクト無事完了

通常業務でも2つ大きなプロジェクトを計画通りにやりきれたので良かった。
(Koudaiiiが何やってるか人かはこちらを見ていただければ。元記事

 

  • ぐいぐい行く!

2013のTryにあった「ぐいぐい行きたい!」を業務でもやろうと思って、
保守が切れるタイミングで、OSからミドルウェアまで、すべてアプリを一切変えずにバージョンアップを行うことにしました。
ベンダーさんも含めて全員反対意見でしたが、やるんだよっと押し切ったのが良かった(?)かな。

MySQL5.0から一気に5.6に変えたのはでかかった。ただ地獄でしかなかった。。


ただ、一旦改善に踏み切ったシステムは慣性の法則が働いて、アプリ側の改善も自然と行うようになって結果的に満足しています^^

 

Problem

Blogが少ないかなあー。こまめに出していく。
(技術系はすべてGistに書いている)

 

Try

 

  • 必ず質問できるようにする!

先日、はてなの栗栖さんの発表見て自分もやってみようと思いました!

 

  • Gistからblogへ移行

このBlogが結構ポエム用になりつつあるから、別で作ってもいいなぁ。

 

 

Rails一本で来ていたので、他のフレームワークを利用してみる(MEAN Stackとか)

  • Blog書くぞ-!

 

ということで最後に今年の漢字は以下にしました。


2015 【発】発信する 。

 

今年もよろしくお願いします╭( ・ㅂ・)و ̑̑ グッ !

答えのない目標に小さな越境を積み重ねる #devlove

この記事は、DevLOVE Advent Calendar 2014 「越境」の50日目の記事です。

前回は、Noritaka Shinohara さんの「自分がやりたいことをやっていたら、いつのまにか「越境」していた話」でした。

LT頑張りました!!

 

Who?

koudaiiiと申します。
6名の部署で、2つのSaaSを運営+SEでオンプレミス案件の保守運用・運営しています。
一応大企業(?)に所属していますが、独自路線色が強いところに在籍しています。
普段はカスタマーサポート兼インフラ兼SE兼事務兼Developer兼営業だったりしていますが、
基本的に手伝えるところは手伝え!みたいなところです。
外でお会いしている方は、インフラのEngineerかDeveloperと思われたりしますが、
メイン業務はカスタマーサポートで、ほとんど電話かMailをしているなような気がします。
この経験はCodeを書く上で非常に役に立っています。
最近では企画書を書いたりしています。

話すこと

「越境」というテーマということで普段の活動を振り返りました。
凡人のため、あまりカッコイイことが言えません><
が!!
小さくて、ちょっとした勇気を振りぼってやったことを書き綴りたいと思います。
長文ですが、お付き合いいただければと思います。
目立った能力もない残念な人の奮闘記だと思っていただければ幸いです><

  1. 価値?
  2. 越境?
  3. 自分の領域
  4. 空間を広げる
  5. いいと思ったらやっていこう
  6. 次の壁
  7. まとめ

価値?

私は価値を届ける(後述)という部分に力を入れています。
どうやったら早くできるか?どうやったら安定するか?どうやったら今より良くなるか?
みたいな部分を考えて必要であればその場で作ったり入れたりしています。
「システムのインフラ」というより「サービスのインフラを見る!」といったイメージです。

 

価値=提供すること/もの(サービスやシステム)と本記事では定義します。

 

動詞を紐付けて職種をざっくり分けると以下の様な形になるかなーと思います。
ちょっと後半を書きやすくするために荒っぽくしていますのでご了承ください><

価値を作る
* Creator(Developer and Designer)
価値を届ける
* Operator(Customer Support & System Operations)
* Sales
価値を見る
* Data&Log Scientist
* Marketer
価値の場を作る
* Management
* Business

越境?

越境とは、境界線に対して飛び超えることです。
この二年間ほどやってきたことをまとめました。
言葉にすると大掛かりに見えますが、
大それたものではなく、
定義した価値を一つ一つ小さく飛び越えて行ったものです。

  • 価値を届けるために、Creator/Salesとの密度な連携へ
  • 価値を届けるために、よりモダンな開発へ
  • 価値を届けるために、ツールを開発を
  • 価値を届けるために、Logの可視化
  • 価値を届けるために、より外部との交流を
  • 価値を届けるために、お客様の不具合調査のためにCode Readingを
  • 価値を届けるために、そもそもの価値を作る

etc...


自分の領域を理解

  •  配属当時

カスタマーサポートという領域は基本的にマンツーマンで回答や事務を進めます。
それ以外に契約の更新やリリースの案内も行います。
顧客対応から顧客管理までを主に行っておりました。
わからない部分があれば、こちらで回答
不具合があれば、開発チームへ連絡
要望があれば、POへ連絡
どっときたかと思えば、全くなかったり結構日々忙しさが変わります。
情報共有は当時非常に少なかったです。

空間を広げる

サポートをやっていくうちにどうもスピード感がいまいちであったり、
自分が成長している実感を得られなくなっていくのを感じました。

 

所属してから半年ぐらいからか少しずつ枠を越えて行きたいと考えるようになりました。その時に、行ったことを今でも覚えていて今も実践しています。

 

とにかく、リーダー的な人に休憩時間を見計らって話にいった

 

とにかく、知識が足りないことと、実績がないことは新人の自分にも明白でした。
ボトムアップ(本を読む)で行くにはあまりりの知らなさすぎました。
また、直近の先輩に聞くのも遠回りだと思い、
直接権限があり、さらにスキルがある現場のリーダーにご教授頂くのが良いと考えました。
そして、知識をもらって、ペアオペをしてもらい、先に進むことになりました。
(当時はペアオペ&ペアプロも知らなかった)

やってきたことは、
最初はインフラの保守。
その後、不具合や障害の切り分け調査、CodeReadingと枠を広げていき、
リリースも行うようになりました。
Developerの補助みたいなところです。

いいと思ったらやっていこう

こうして、
他のリーダーのところに行くという小さな勇気?というか当たり前なことをして
少しずつ越境していきました。

 

  • 3年前くらい?

しかし、配属して少しするとなぜか先輩がどんどんいなくなるという事件?が発生し、
また途方にくれることになります。(結局1人に…)

 

2012年10月9日に同期と一緒にコミュニティ参加することにしました。

経緯は覚えていませんが、
一人で業務を行うことが多くなり、
また成長が鈍化していくことに危機感を覚えていたのは覚えています。
独立して進む必要があると自分で感じていました。
そこへ鍵となったのが勉強会(コミュニティ)です。
今は、そこで収集し、やってみて、有用であれば取り入れるという活動を行っています。

 

ある程度TRY&ERRORを繰り返すうちにそれぞれのチームから要望聞いて作るという形に変わっていきました。

  • Developerであれば、CI環境を!
  • Dataを見たいのであれば、Logからグラフを!
  • Salesであればどこに課題を持っているのか?提供速度?デモデータ作るの大変?じゃあ作っておきます!

 

  • 価値を届けるために、より自動化を進める
  • 価値を届けるために、価値を作る
  • 価値を届けるために、価値を見る


また、勉強会参加していく中で、自ら発信しないと得るものが少ないなぁーと思い始めました。
そこで、まずは社内で発信することにしました。
発信側に立つとその場での知り合いが参加者に比べ、一気に変わります。
また懇親会参加でも、一気に変わります。
自然と輪が広がっていき、少しずつ情報が入ってくるようになっていきました。
幸いにも今年は定期的に発表する機会を頂きました。

次の壁

さらに先へ進むために、変える必要があると最近感じるようになってきました。
それは、先週にPull Requestを送った時です。
Reviewを受け、お互いの意見を言い合う場が今まで自分にはなかったなぁと考えさせられる瞬間でした。
環境によっては当たり前な話ですが、、危機感を感じる年末になってしまいました。。。
まだまだ、発展途上だ。

 

PullRequestは新しくv1.1.0されました。


Release mackerel-agent-plugins · mackerelio/cookbook-mackerel-agent · GitHub

 


まとめ

  • 達成することがない目標(価値)をもつことでモチベーションを維持
  • 小さな勇気で小さく行うことで世界が広がる
  • 越境するには、まず境界線を把握
  • 自分の領域を広げることで、それは過去の自分から越境している
  • 今困ってます!


次回はひろみつさんです!
よろしくお願いします!