c81.tex

\documentclass{jarticle}
\title{英語でコミットメッセージを書こう}
\author{同人サークル NP-complete}
\date{2011/12/31\\コミックマーケット81}
\renewcommand\thefootnote{[\arabic{footnote}]}
\usepackage{ascmac}
\usepackage{fancybox}


\begin{document}
\Huge
\maketitle
\normalsize
\thispagestyle{empty}
\newpage
\thispagestyle{empty}
\-
\newpage
\section*{伝説のコミット}
{\bf {\Large ``} }
{\it GIANT BUG... causing /usr to be deleted... so sorry....
 issue \#123, issue \#122, issue \#121}
{\bf {\Large ''} }
\begin{flushright}
 -- MrMEEE\footnote{https://github.com/MrMEEE/bumblebee/commit/a047be85247755cdbe0acce6}
\end{flushright}

\vspace{1in}

{\tt
\begin{verbatim}
@@ -348,7 +348,7 @@ case ``$DISTRO'' in
   ln -s /usr/lib/mesa/ld.so.conf /etc/alternatives/gl_conf
   rm -rf /etc/alternatives/xorg_extra_modules
   rm -rf /etc/alternatives/xorg_extra_modules-bumblebee
-  rm -rf /usr /lib/nvidia-current/xorg/xorg
+  rm -rf /usr/lib/nvidia-current/xorg/xorg
   ln -s /usr/lib/nvidia-current/xorg
 /etc/alternatives/xorg_extra_modules-bumblebee
   ldconfig
  ;;

\end{verbatim}
}

\newpage
\section{まえがき}
みなさん、github\footnote{https://github.com}使ってますか?
もちろん使ってますよね!
githubでコードを公開した瞬間から、あなたはオープンソースのプログラマです。

世界中の誰もがあなたのコードにアクセスすることができます。
全然知らない国の人があなたのコードに改良を加えて、
pull requestしてくれるかもしれません。

あなたがコミットメッセージを英語で書いてさえすればね!!!

\subsection{英語でコミットメッセージを書こう}
英語でコミットメッセージを書こうっていきなり言われても困りますよね。
多分技術者なら読む方はある程度できると思います。
たくさん英語のドキュメント読んでますよね?

書く方なんてやったこと無いよって思い込んでませんか?
実はほとんどの人が英語に近い文章を日々たくさん書いているはずです。
そうです、コードです。

\subsection{なぜコードは英語で書けるのか}
言語を覚えたりコードを書く際には言語のドキュメントや他の人が書いたコード
を大量に読みます。
コードを大量に読めば、自然とその言語の標準的な命名ルールや、
定番の変数名に気づくことになるでしょう。

多くの人は、他人のコードを読むことで自然と覚えた英単語を組み合わせ、
自分のコードを書いているのではないでしょうか?
ドキュメントを読むことよりも、求められる英語力は低いのではないかと思いま
す。
\subsection{同じことをコミットメッセージにも}
同様にコミットメッセージも、標準的な単語や、
定番の言い回しなどを列挙さえすれば、
必要十分なコミットメッセージは簡単に書けるようになりそうです。

この本の目的は、そのような定番を見つけ出し、
簡単に英語でコミットメッセージを書けるような材料を揃えることです。
そして日本人のプロダクトに言語の壁と国境をなくすことです。

\newpage
\section{調査方法}
リポジトリの調査に使ったスクリプトは全て公開
\footnote{https://github.com/np-complete/c81}しています。
まずこのリポジトリをチェックアウトしましょう。
実際にあなたの好きなプロジェクトを選んで同じ調査を実行することができます。

次に、githubで調査対象にしたいリポジトリを探し、
{\tt src } ディレクトリにチェックアウトしておきます。
もちろんコミットメッセージが英語で書かれているものですが、
英語ネイティブ/非ネイティブ両方を調べたほうがいいかもしれません。
もちろん、自分が興味を持てるプロジェクトを最優先したほうがいいでしょう。

今回、
git\footnote{https://github.com/git/git},
linux\footnote{https://github.com/torvalds/linux},
ruby\footnote{https://github.com/ruby/ruby},
rails\footnote{https://github.com/rails/rails},
jquery\footnote{https://github.com/jquery/jquery},
node\footnote{https://github.com/joyent/node}
などを調査対象にしました。

また、git以外のリポジトリでも、
コミットメッセージさえ取得できれば同じスクリプトで調査ができるはずです。

\section{単語を調べる}
まず最初にどのような単語がよく使われているかを把握しましょう。

gitでは、
\begin{quote}
{\tt \$git log --pretty=\%s\%n\%b\%n}
\end{quote}

というコマンドでコミットメッセージ部分だけ見ることができます。

このスクリプトを {\tt c81/bin/only-message } に置いてあります。
次のようにファイルに保存しておくとよいでしょう。
\begin{quote}
{\tt \$cd src/rails; ../../bin/only-message > ../../data/rails-messages }
\end{quote}

メッセージから余分な文字や記号を削除して、
単語に分割しやすくするスクリプトが {\tt c81/bin/word-format} です。
先程の出力をこのスクリプトに通しておきましょう。
\begin{quote}
{\tt \$./bin/word-format ./data/rails-messages > ./data/rails-words }
\end{quote}

これで素のコミットメッセージが単語に分割しやすい形になりました。


  \subsection{文頭の単語を調べる}
  英語の文章は一番言いたいことを先に書くっていうルールがあります。
  とりあえず文頭の単語を調べてみましょう!
  \begin{quote}
   {\tt \$./bin/first-word ./data/rails-words | ./bin/counter > ./data/rails-first-word}
  \end{quote}


  \begin{table}[htbp]
   \begin{center}
    \begin{tabular}{c}

     \begin{minipage}{0.3\hsize}
      \begin{center}
       \caption{rails の場合}
       \begin{tabular}{c|c}
        \hline
        1670 & fix \\
        1519 & merge \\
        1369 & added \\
        1274 & add \\
        1030 & fixed \\
        843 & remove \\
        683 & make \\
        632 & use \\
        532 & this \\
        456 & update \\
        339 & ensure \\
        324 & revert \\
        311 & move \\
        303 & don \\
        282 & allow \\
        225 & removed \\
        \hline
       \end{tabular}
      \end{center}
     \end{minipage}

     \begin{minipage}{0.3\hsize}
      \begin{center}
       \caption{node の場合}
       \begin{tabular}{c|c}
        \hline
        513 & add \\
        485 & fix \\
        216 & upgrade \\
        205 & remove \\
        201 & this \\
        178 & fixes \\
        99 & http \\
        96 & use \\
        90 & the \\
        89 & - \\
        84 & bump \\
        82 & closes \\
        76 & merge \\
        66 & revert \\
        62 & make \\
        61 & update \\
        \hline
       \end{tabular}
      \end{center}
     \end{minipage}


     \begin{minipage}{0.3\hsize}
      \begin{center}
       \caption{jquery の場合}
       \begin{tabular}{c|c}
        \hline
        366 & added \\
        295 & fixed \\
        251 & fix \\
        192 & merge \\
        189 & jquery \\
        180 & make \\
        93 & fixes \\
        77 & removed \\
        67 & - \\
        65 & made \\
        56 & add \\
        51 & tagging \\
        49 & updating \\
        46 & landing \\
        43 & more \\
        41 & updated \\
        \hline
       \end{tabular}
      \end{center}
     \end{minipage}

    \end{tabular}
   \end{center}
  \end{table}

  ほとんどが動詞ですね!
  さらに3つのプロジェクトで共通して出てくる単語がいくつかあります。
  {\bf fix}, {\bf add}, {\bf remove}, {\bf make}, {\bf update} です。
  これらの単語は異常によく使われる単語だというのがわかりますね。

   \subsubsection{文脈を確認する}

   {\bf make} と {\bf update} は少し意味が分かりづらいので文脈を確認します。
   {\tt c81/bin/grep-first}スクリプトを使い、{\tt grep} で頭文字が一致する文を抜き出しましょう。

   \begin{quote}
    {\tt \$./bin/grep-first make ./data/rails-words }
   \end{quote}

   例えばこんな文章が出てきます。
   \begin{quote}
    {\bf make} all tests pass on pgsql \#1759 rick olson\\
    {\bf make} sure that we get back a soapstring when \$kcode is utf-8\\
    {\bf make} request\#subdomains handle foo foo com correctly\\
   \end{quote}
   どうやらナニナニをチョメチョメな状態にするという意味のようです。

   同様にupdateも調べてみました。
   どうやらupdateは
   {\bf makeと同じような使い方{\footnote{例) update jquery data to use jquery noop for tojson hack instead of an additional superfluous function}}} や
   {\bf 関連ライブラリをupdateした{\footnote{例) update to prototype 1 5
   0 }}} など様々な意味で使われているようでした。
   {\bf make} と {\bf update} の微妙なニュアンスの違いはよく分かりません。

  \subsubsection{まとめ}
  自分がやったことを表現するには次の単語を文頭に使うと良い。
  \begin{table}[htbp]
   \begin{center}
    \begin{tabular}{ll}
     fix & バグを修正した \\
     add & 機能やファイルを追加した \\
     remove & 機能やファイルを削除した \\
     make & 変更した(動作が明確に変わるとき) \\
     update & 更新した(外部ライブラリやドキュメント) \\
    \end{tabular}
   \end{center}
  \end{table}

  削除や変更という単語で、一番最初に思い浮かびそうな {\bf delete} や {\bf change} は、
  実はあまり使われていない。

  \subsection{目的語を調べる}
  前節で文頭に特徴的な動詞が多いことが分かりました。
  次は何を~に当たる部分の特徴を探しましょう。
  前節で使った頭単語検索を使い、2-4語目を抜き出してみましょう。

   \begin{quote}
    {\tt \$./bin/grep-first fix ./data/ruby-words | cut -f2,3,4 -d ' ' | ./bin/counter }
   \end{quote}

   \subsubsection{fix}
   修正対象の表現として、
   {\bf typo}\footnote{rubyはtypoの割合が圧倒的に多い} や
   {\bf bug}, {\bf error}, {\bf problem},
   {\bf issue}\footnote{BTSのチケット番号を添える場合に使うことが多い}
   などが使われています。

   {\bf fix variable name}や、
   {\bf fix memory leak} などのように問題の原因を直接書くことも
   あります。

   名詞を修飾する語として、
   {\bf fix wrong class name} や {\bf fix wrong test} のように
   {\bf wrong}が使われることが多いようです。

   \subsubsection{add}
   {\bf test}, {\bf document}, {\bf comment}などがよく追加されるようです
   \footnote{どのプロジェクトも機能追加よりテストやドキュメントの追加の
   ほうが多いようです}。
   最もたくさん追加されているはずなのに、
   {\bf bug}という語が見つかることはないでしょう。
   また、新規のファイルを追加しても、
   {\bf add file}のような使い方はしないようです。

   新しい機能の追加には
   {\bf method}, {\bf function}, {\bf process}, {\bf code}
   などが使われ、
   直接メソッド名を書く方法もあります。
   あまり{\bf feature}という語は使われないようです。
   既存メソッドの機能追加も {\bf add option} や {\bf add parameter} などで、
   addを使って表現する場合もあります。

   プラットフォームやデバイスやOSへの対応は{\bf add support}で表現されま
   す。

   \subsubsection{remove}
   基本的に{\bf add}できるものは、当然{\bf remove}にも使えます
   \footnote{ただし一番消されるのは残念ながらsupportのようです}。
   削除の理由を表すために、{\bf unused}, {\bf unnecessary},
   {\bf extra}, {\bf duplicated} などの修飾子を使います。

   修飾対象の名詞には、addで使われるものよりも、
   {\bf variable}, {\bf method}, {\bf file}, {\bf code}などを使って
   もっと限定的に削除箇所を表現します。

   単純に空行の削除や空ディレクトリの削除には、
   {\bf empty line} や {\bf empty directory} などが使われます。

   \subsubsection{make}
   makeは圧倒的に慣用句表現が多く見られます。
   {\bf make sure that ...} や {\bf make it ... to} のような表現です。

   ここで特徴的なのは、ほとんどが{\bf make sure}なjqeryに比べて、
   rubyには1度しか使われておらず、そもそも{\bf make}の使用回数も少ないところです。
   railsにも{\bf make sure}が多いところを見ると、
   非英語ネイティブは{\bf make}の使い方が上手くないのかもしれません
   \footnote{matzはrubykaigiで通訳を務めるくらいの英語能力なので単純に好
   みの問題の可能性もあります}。
   {\bf make sure}を上手く使いこなすことでカッコよくコミットしましょう!

   \subsubsection{update}
   {\bf document}や{\bf test}など{\bf add}と同じものが似たような意味で使われる
   ようです。
   {\bf fix}でもなく{\bf add}でもなく{\bf update}という微妙な雰囲気を感
   じ取ってください。

   それ以外にも{\bf version}などの数値を上げるときにも使います。

  \subsection{おまけ}
  単語数をカウントしてみると今まで見たこともない単語が見つかることがあり
  ます。

  例えばrubyのコミットメッセージには約4000回 {\bf ditto} という単語が出
  てきますが、こんな単語見たことありますか?
  どうやら調べてみると「同上」という意味で、
\begin{verbatim}
* vm.c (rb_vm_rewrite_dfp_in_errinfo): change return type
   to suppress a warning.
* vm_core.h: ditto.
\end{verbatim}
  のように使うようです。

  他のプロジェクトを調べてみるとlinuxで46回、railsで2回。
  全く使われないわけではないけれどほとんど使われないような単語が、
  rubyでは4000回も使われるという点で、
  コミットの語彙にも文化があると言えるのではないでしょうか。

  \newpage
 \section{内容を説明する}
 コミット内容から、動詞と目的語は簡単に決めることができるはずです。
 しかし、ほとんどの場合は、もっと具体的な内容を書かないといけませんね。

 もちろんこの行為は非常に高い英語力を求められます。
 さてどうしましょう?

  \subsection{パクる}
  既存のコミットメッセージをパクりましょう!
  {\bf grep}を駆使して似たようなコミットを探すのです。

  例えば、ss\_editor\footnote{https://github.com/np-complete/ss\_editor} の
  コミット 92f6b8a92\footnote{https://github.com/np-complete/ss\_editor/commit/92f6b8a92ec938e6f74d919b52e3ba3cb2e73a4d}
  を英語にしてみましょう。
  このコミットの内容は、{\tt before\_filter} にストーリーの所有者である
  ことを確認する処理を追加するというものです。

  まず動詞は当然 {\bf add} を使えばいいでしょう。
  目的語はとりあえず {\bf filter} を想定してgrepしてみます。
  パクり元のプロジェクトとして、最も有名なRailsアプリケーションの
  ひとつであるRedmine\footnote{https://github.com/edavis10/redmine} を使
  います。

  \subsubsection{全然ダメだった}
  \begin{quote}
   {\tt \$grep -i add data/redmine-message | grep -i filter }
  \end{quote}
  どうやら出てくるのはほぼSQLの条件設定の話ばかりで参考になりません。

  \subsubsection{かなり近づいてきた}
  次に {\bf permission} を思いついたので検索してみます。
  \begin{quote}
   {\tt \$grep -i add data/redmine-message | grep -i permission }
  \end{quote}

  今回のはかなりイイ線いったメッセージが出てきます。
  例えば、
  \begin{quote}
   {\tt Adds permissions to let users edit and/or delete their messages }
  \end{quote}
  なんかいい感じですね。
  これを参考に書いてみましょう。
  \begin{quote}
   {\tt add permission to let users access only their own stories }
  \end{quote}
  なんてどうでしょう?

  \subsubsection{これならどうだ}
  制限が増えてるのに {\tt add permission} は少しおかしいので、
  別の候補も探しましょう。{\bf check} で調べてみることにしましょう。

  \begin{quote}
   {\tt Add etag check on the activity view to avoid rendering when not
   modified.}
  \end{quote}
  これ良いですね、パクりましょう!
   \begin{quote}
    {\tt add permission check on the stories\_controller.rb to avoid accessing when not own.}
   \end{quote}
   {\tt when not own.}の部分にまだ違和感がありますが、こっちのほうがシックリきますね!!

  \subsection{前置詞}
  自信を持って英語を書けない一番のポイントが前置詞ではないでしょうか?
  inとonの違いとか分かりますか? 全然分かりませんよね。

  色々調べてみたところネイティブの人たちも結構適当に使っているようでした。
  常識的におかしくない使い方なら大丈夫でしょう。
  {\tt test for}だけはお決まりらしいのでおさえておきましょう!

  \subsection{まとめ}
  スラスラ書けるようになるには、リアル英語力が必要そうです。 orz\\
  ううむ、この本の存在意義とは \dots

 \section{結論}
  英語力は必要ぽいです。
  ごまかせるのは動詞まででした。

  よいプログラマになるにはたくさんコードを読みましょうというのと同様に、
  よいコミットメッセージを書くにはたくさんコミットメッセージを読みましょ
  う。

  としか言えない \dots

  \begin{center}
  \Large
   当初のもくろみは完全に失敗でした!\\
   みんな素直に英語を勉強しよう!!!
  \end{center}


  \newpage
   \section*{あとがき}
  「あずにゃんとペアプロしてる気分になれる本」に続く第2弾です。
  いかがでしたでしょうか。

  \subsection*{反省点}
  今回の本、想像以上に難航しました。
  コミットメッセージなんて決まりきった形式で書かれてるんじゃねえのー?
  と思って始めてみたんですが、プロジェクトごとに全然違うんですねぇー。
  5つの動詞はかろうじて正解だと言えそうですが、
  それ以降に関してはほとんど無理やりデータを導きだしてます。

  特に定型文のようなものもなく、決まりきった表現のようなものもなく、
  ふっつううううに英文がつらつら書かれているようで、
  つまり何もズルするところがなく英語力が求められるという最悪な自体に直面
  してどうしようかと思いました。
  最終的には他のコミットメッセージのパクり方を調べるという方法で逃げまし
  た。

  \subsection*{\TeX へのうらみつらみ}
  あと綺麗な組版がしたくて \TeX で書いてみたけどこれも大失敗でしたね。
  今更 \TeX はないわーと実感しました。
  もっと簡単なマークアップ言語使えばよかったと後悔しました。
  特にテーブル組とか最悪です。
  \TeX を使いたい理由は唯一footnote\footnote{これのこと}なので、
  これができる簡単なマークアップ言語があればそっちを使いたいです。
  でも無いんだろうなぁー。

  あとEUCじゃないとダメってのがもう死ねばいいと思いました。
  絶対EUCなんかでファイル書きたくないので、
  わざわざMakefileで変換したり面倒なことをしています。
  もうたぶん \TeX は二度と使わないでしょう \dots
  数式を書くような仕事もないだろうし \dots

  \subsection*{総括}
  全体的に見たら不完全燃焼なプロジェクトでした。
  まあ素直に英語を勉強しろという答えが導き出せたのはよかったと思います。

  みんな英語勉強して世界出ていこうぜー

  \begin{flushright}
   Enjoy, Programming!\\
   \large{まさらっき}
  \end{flushright}

  \newpage
  \section*{告知}
  ニコ生でプログラミング生放送やってます。
  ruby中心で作業を垂れ流ししてます。
  たまに絵を描いたり原稿を書いたりもしてます。
  \begin{quote}
   {\tt http://com.nicovideo.jp/community/co600306}
  \end{quote}

  リアル仕事はニコニコ静画(電子書籍)の中の人をやっています。
  無料漫画だけでも読みきれないほどコンテンツが充実してきたのでどうぞ見て
  やってください。
  おすすめは
  \begin{quote}
   {\tt http://seiga.nicovideo.jp/watch/bk686}\\
   {\tt http://seiga.nicovideo.jp/watch/bk1169}
  \end{quote}
  です。

  あと、次回はgit本出そうと思ってます。
  gitでワークフローを上手く回すマニュアルみたいなのを。
  あとブランチを擬人したマンガ出したいっすねー。
   \huge{{\bf  master総受け}}
   \normalsize{的なやつを}

  \newpage
  \begin{center}
   \Large
   \section*{奥付}
   {\huge コミットメッセージを英語で書こう}
   \\[2.0cm]
   発行\\
   NP-complete\\
   http://np-complete-doj.in
   \\[1.5cm]
   著者\\
   まさらっき\\
   http://twitter.com/masarakki
   \\[2.5cm]
   発行日\\
   2011/12/31
  \end{center}
  \newpage
  \thispagestyle{empty}
  \-
  \newpage
  \begin{flushright}
   \-
  \end{flushright}

  \thispagestyle{empty}
\end{document}