良いソフトウェアに求められる３点セットとJSXの開発手法の改善とgit-pushdirについて

テスト駆動開発（TDD）の一般化とGitHubの登場によって、機能追加の際にコードとテストを同時に実装する（そして、両者を一括してmasterにmergeする）という開発手法が一般化してきました。

しかし、「良いプログラム」の要素を構成するのは、コードとテストのみではありません。動作するコードと、その品質を担保するためのテストがあったとしても、適切なドキュメントがなければ、ユーザーはそのプログラムをどうやって使ったら良いかわかりません。

つまり、ユーザーに使いやすいプログラムを継続的に開発／提供しようと思うと、

• コード
• テスト
• ドキュメント

の３点セットを提供する必要があるのです^注1。

今日のJSXが抱えている最大の課題は、ドキュメントが不足しているという点にあります。その原因は、「機能追加」の際にコードとテストのみを実装してmasterにmergeすることを繰り返す一方で、ドキュメントはプロジェクトページのレポジトリとして別個に更新作業を行ってきた^注2点にあり、その結果、コードとテストは存在するが対応するドキュメントがない機能がいろいろ実装されてきてしまった、と認識しています。

以上の認識に基づき、JSXでは今後、プロジェクトページを含む全てのドキュメントをJSX本体のレポジトリで管理することにしました。機能を追加（≒プルリクエストをマージ）する際には、コードとテストとドキュメントの３点セットを準備したのちにmasterへmergeする、というやり方で行きたいと考えています。

また、そのために、git-pushdirというスクリプトを書きました。このスクリプトは、あるディレクトリの中にあるファイルを丸ごと、指定したGitレポジトリにpushすることができます。JSXではこのスクリプトをMakefileから以下のように呼び出すことで、リリースの際に自動的にプロジェクトページのドキュメントを更新するようにしました。

publish: publish-test
        npm publish
        $(MAKE) doc-publish

doc-publish: doc
        (cd doc/jsx.github.com && ../../tool/git-pushdir -m "`git log --format='doc at commit %h' | head -1`" git@github.com:jsx/jsx.github.com.git)

似たようなことはgit subtreeを使っても可能^注3ですが、subtreeの定義やpullした場合のconflictに絡む問題がない点がgit-pushdirの優位性になるかと思います。  つーことでよろしくお願いします＞関係者諸氏。

注1: テストを書くコストが見合わない、あるいはドキュメントなど不要というケースもあるとは思います
注2: jsxdoc（javadocライクなツール）が出力するAPIリファレンスではなく、言語仕様に関わる文書のようなものについて述べています
注3: 参照: git subtreeで自動生成ドキュメントをGitHub Pagesに連携してみた - Life goes on