commit-comment-tools 0.0.1

data/doc/text/news.md

@@ -0,0 +1,5 @@
+# News
+
+## <a id="0-0-1">0.0.1</a>: 2013-04-11
+
+The first release!

data/doc/text/scenario.txt

@@ -0,0 +1,168 @@
+# -*- org -*-
+#+STARTUP: overview
+#+STARTUP: hidestars
+
+* 導入研修
+
+研修でやることの説明をする。↓のリストを読んでやることの説明をする。全
+体の流れを説明する。
+
+  - 「リーダブルコードの解説」を読む (10分)
+    http://www.clear-code.com/blog/2012/6/11.html
+
+「リーダブルコードの解説」を読むことで須藤が考える「リーダブルコードを
+書くために必要なこと」を知ってもらいます。
+
+  - 「リーダブルコードの解説」の解説 (5分)
+
+「リーダブルコードの解説」を書いた時点と現在では、須藤の考え方も変わっ
+ているため、考え方の変わった部分について説明します。
+
+  - 「Ruby コードの感想戦 【第 1 回】 WikiR」を読む (20分)
+    http://jp.rubyist.net/magazine/?0040-CodePostMortem
+
+他の人がどんな読み方をするのか知っておくと、コードを読むときの視点が増
+えるので、その一例として須藤の読み方を知ってもらいます。
+
+  - 「Ruby コードの感想戦 【第 1 回】 WikiR」の解説 (5分)
+
+須藤がどういう読み方をしていたのか簡単に解説したあと、参加者のみなさん
+に普段どのようにしてコードを読んでいるのか聞きます。
+
+そのあと、講師の読み方を説明します。
+
+  - 実際にやってもらう (10分)
+
+1人ずつ2,3分くらいで実際にコミットメールを読んでもらいます。
+1人がやっている間、他の人はその人の周りに集ります。
+
+  - 感想を聞く (10分)
+
+やってもらった感想を聞く。
+
+  - コメントの仕方 (5分)
+
+どういう点に注意してコメントをするのか説明します。
+
+  - まとめ (5分)
+
+** 「リーダブルコードの解説」を読む (10分)
+
+「リーダブルコードの解説」を10分くらいで読んでください。
+http://www.clear-code.com/blog/2012/6/11.html
+
+「リーダブルコードの解説 ククログ」でぐぐると一番上に表示されます。
+
+リーダブルコードの解説にはリーダブルなコードを継続的に書くために必要な
+ことが書いてあります。また、リーダブルなコードを書くことを始めたばかり
+の頃に困りそうなことも書いてあります。
+
+
+(大きめの字で印刷して配ってもいいかも)
+
+** 「リーダブルコードの解説」の解説 (5分)
+
+「リーダブルコードの解説」には、まず自分がリーダブルなコードを書くんだ
+というようなことが書かれていますが、普通の人はいきなりリーダブルないい
+コードを書くことはできません。なぜなら、いいコードを読んだ経験がないか
+らです。いいコードを読んだ経験がないと、いいコードを書くことは難しいの
+で、まずはコードを読む習慣をつける必要があります。
+
+いいコードは読みやすく、コミットメールに載っている差分だけ読んでも書い
+た人の意図が理解できるものです。一方、よくないコードは、コミットメール
+に載っている差分だけ読んでも、よくないコードであることがわかることが多
+いです。なぜなら、よくないコードは何かしら「歪み」や「臭い」を持ってい
+るからです。
+
+コミットメールを読んで、読みやすいと思ったコミットやいい書き方をしてい
+るなと思ったコミットは書き方を真似て、自分のコミットに取り入れてくださ
+い。そのコミットに使われていた書き方を使うと、真似された方は真似されて
+いることに気付きます。同じ書き方を使ったコミットが増えるとまわりの人も
+気付いて真似するので、いいコードが広まるという流れになればいいと思って
+います。
+
+そして、コミットへのコメントサービスでは、コミットメールを読む習慣作り
+の最初の一歩目をお手伝いします。
+
+
+** 「Ruby コードの感想戦 【第 1 回】 WikiR」を読む (20分)
+
+「Ruby コードの感想戦 【第 1 回】 WikiR」を10分くらいで読んでください。
+http://jp.rubyist.net/magazine/?0040-CodePostMortem
+
+他の人がどんな読み方をするのか知っておくことは重要です。なぜなら、コー
+ドを読むときの視点が増えるからです。コードを読むときの視点が増えると、
+視野が広くなり、自分がコードを書くときの引き出しが増えます。他の人のコー
+ドの読み方の一例として須藤がコードを読むときにどんなことを考えながら読
+んでいるかを知ってもらいます。
+
+Rubyの機能やライブラリの説明が何ヶ所かありますが、その部分は「ふーん、
+そうなのか」程度で流し読みしてもらって大丈夫です。
+
+(大きめの字で印刷して配ってもいいかも)
+
+** 「Ruby コードの感想戦 【第 1 回】 WikiR」の解説 (5分)
+
+須藤の読み方は、書いた人の意図を想像しながら読むというものでした。しか
+し、中にはあまり意図などなく書いている人もいます。
+
+普段、どのようにしてコードやコミットメールを読んでいますか？
+(順番に聞いていく)
+(今後に活かすため、記録する)
+
+講師のコミットメールの読み方を説明します。
+
+  - コミットログを読む
+  - コミットの内容とコミットログの内容が一致しているか確認する
+  - 一致していないときは注意して読む
+  - 一致しているときは、流し読みする
+  - あんまり難しいことは考えない
+  - 間違いを見つける意識では読まない
+
+あと、自分にとって重要なプロジェクトかどうかで変わります。
+
+** 実際にやってもらう (15分)
+
+# 具体的な案はないが、毎回初見のコミットメールを用意するのは大変かも。
+# 他の導入先のコードは初見のはずなので特に問題ないか
+
+対象プロジェクトのコミットのうちそのときの最新10から20コミットくらいでやる。
+
+- 自分がやる(3分)
+- 1人3分でやってもらう(10分)
+
+もっと長い時間やったときは記録も付けてもらう
+
+- 記録を付けてもらう(2分)
+  - 読んだ割合(ざっくり)、印象に残ったコミット
+
+** 感想を聞く (10分)
+
+それぞれの人に感想を聞く。
+
+- 読んでみてどうだった？
+- 気になったことは？
+
+(感想など聞いた話は次に活かすために記録する)
+
+** コメントする方法を説明する (5分)
+
+- 場所。気になったのはどこかを書く。
+- 理由。なぜ気になったのか。○○だから読みにくい。理由がなければ無いこ
+  とを書く。
+- 改善案。改善案があるかないか。改善案があればそれを書く、改善案がなけ
+  れば無いことを書く。
+
+** まとめ (5分)
+
+例えば、コミットメールを読むのに使う時間は一日30分までと決めると、時間
+を使い過ぎることはなくなるので、試してほしいです。徐々にコミットされる
+コードが読みやすくなってくれば、読めるコミットメールの数や割合が増えて
+くると思います。
+
+質問はありますか？
+
+他に気になることはないですか？
+
+(何度か質問を繰り返して、疑問点を出してもらってできるかぎり解消しておく。)
+(また、出てきた質問と回答はメモを取っておいて、次回以降に活かす。)

data/lib/commit-comment-tools/entry.rb

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2013  Haruka Yoshihara <yoshihara@clear-code.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+require "date"
+
+module CommitCommentTools
+  class Entry
+    class InvalidEntryError < StandardError
+    end
+
+    attr_reader :name, :date, :read_ratio, :comment
+
+    def initialize(name, entry_chunk)
+      @name = name
+      @date = nil
+      @read_ratio = nil
+      @comment = nil
+
+      if /\A(\d\d\d\d-\d+-\d+):(\d+)%:(.*)\z/m =~ entry_chunk
+        @date = Date.parse($1).strftime("%Y-%m-%d")
+        @read_ratio = $2.to_i
+        @comment = $3
+      else
+        valid_format = "DATE:READ_RATIO%:COMMENT"
+        error_message = "The expected format of entry like below:\n" +
+                          "\"#{valid_format}\", but was \"#{entry_chunk}\"."
+        raise(InvalidEntryError, error_message)
+      end
+    end
+  end
+end

data/lib/commit-comment-tools/generator.rb

@@ -0,0 +1,4 @@
+module CommitCommentTools
+  module Generator
+  end
+end

data/lib/commit-comment-tools/generator/csv.rb

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2013  Kenji Okimoto <okimoto@clear-code.com>
+# Copyright (C) 2013  Kouhei Sutou <kou@clear-code.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+require "csv"
+
+module CommitCommentTools
+  module Generator
+    class CSV
+      def initialize(reports, options={})
+        @reports = reports
+        @options = options
+      end
+
+      def generate
+        members = []
+        daily_read_ratios = {}
+        @reports.each do |name, diaries|
+          members << name
+          diaries.each do |date, report|
+            daily_read_ratios[date] ||= {}
+            daily_read_ratios[date][name] = report[:read_ratio]
+          end
+        end
+        sorted_members = members.sort
+        csv_string = generate_csv(sorted_members, daily_read_ratios)
+        # TODO write to file
+        puts csv_string
+      end
+
+      private
+      def generate_csv(members, daily_read_ratios)
+        ::CSV.generate do |csv|
+          csv << ["DATE", *members]
+          daily_read_ratios.sort_by {|date, _| date}.each do |date, read_ratios|
+            row_values = daily_record2row(read_ratios, members)
+            csv << [date, *row_values]
+          end
+        end
+      end
+
+      def daily_record2row(read_ratios, members)
+        members.collect do |name|
+          read_ratios[name] || 0
+        end
+      end
+    end
+  end
+end

data/lib/commit-comment-tools/generator/graph.rb

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2013  Haruka Yoshihara <yoshihara@clear-code.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+require "gruff"
+
+module CommitCommentTools
+  module Generator
+    class Graph
+    end
+  end
+end

data/lib/commit-comment-tools/report-normalizer.rb

@@ -0,0 +1,58 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2013  Haruka Yoshihara <yoshihara@clear-code.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+require "date"
+
+module CommitCommentTools
+  class ReportNormlizer
+    class << self
+      def normalize(parsed_reports)
+        new.normalize(parsed_reports)
+      end
+    end
+
+    def initialize
+      @person_reports = {}
+    end
+
+    def normalize(parsed_reports)
+      parsed_reports.each do |person, daily_report|
+        normalize_daily_report(person, daily_report)
+      end
+      @person_reports
+    end
+
+    def normalize_daily_report(person, daily_report)
+      @person_reports[person] = {}
+
+      daily_report.each do |date, report|
+        normalized_date = normalize_date(date)
+        @person_reports[person][normalized_date] = normalize_report(report)
+      end
+      @person_reports
+    end
+
+    def normalize_date(date)
+      Date.parse(date).strftime("%Y-%m-%d")
+    end
+
+    def normalize_report(report)
+      report[:read_ratio] = report[:read_ratio].to_i
+      report
+    end
+  end
+end

data/lib/commit-comment-tools/report-parser.rb

@@ -0,0 +1,98 @@
+# -*- coding: utf-8 -*-
+#
+# Copyright (C) 2013  Haruka Yoshihara <yoshihara@clear-code.com>
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+require "English"
+
+module CommitCommentTools
+  class ReportParser
+    class << self
+      def parse(report_directory=nil)
+        report_directory ||= "."
+        report_unexpanded_path = File.join(report_directory, "**", "*.txt")
+        report_file_paths = Dir.glob(report_unexpanded_path)
+
+        new.parse(report_file_paths)
+      end
+    end
+
+    def initialize
+      @person_reports = {}
+    end
+
+    def parse(report_files)
+      report_files.each do |report_file|
+        person_name = File.basename(report_file, ".txt")
+        next unless person_name == person_name.downcase
+        daily_entries = parse_file(report_file)
+        @person_reports[person_name] = generate_daily_report(daily_entries)
+      end
+
+      @person_reports
+    end
+
+    def parse_file(report_file)
+      File.open(report_file, "r") do |report_io|
+        parse_stream(report_io)
+      end
+    end
+
+    def parse_stream(report_io)
+      entries = []
+      date = ""
+      read_ratio = ""
+      comment = ""
+
+      report_io.each_line.with_index do |line, line_number|
+        case line.chomp
+        when /\A(\d\d\d\d-\d+-\d+):(\d+)%:?(.*)\z/
+          unless line_number.zero?
+            entries << entry(date, read_ratio, comment)
+          end
+
+          date = $1
+          read_ratio = $2
+          comment = $3
+        when /\A\s+/
+          comment << $POSTMATCH << "\n"
+        end
+      end
+
+      unless comment.empty?
+        entries << entry(date, read_ratio, comment)
+      end
+      entries
+    end
+
+    def entry(date, read_ratio, comment)
+      {
+        :date       => date,
+        :read_ratio => read_ratio,
+        :comment    => comment.chomp
+      }
+    end
+
+    def generate_daily_report(entries)
+      daily_report = {}
+
+      entries.each do |entry|
+        date = entry.delete(:date)
+        daily_report[date] = entry
+      end
+      daily_report
+    end
+  end
+end