Markdown Driven Issue Managementツールを作った。

はじめに

Diffissueというツールを昨日つくりました。

gitlab.com/ryo33/diffissue

この記事ではこのツールが何者なのかとか何を可能にするのかとか、いろいろ説明していきます。

Diffissueがなにをするか

GitHubやGitLabなどGitホスティングサービスはいくつかありますが、それらには何かしらの開発支援機能がついています。そのなかでもissue機能は様々なものに使えるので広く使用されていると思います。例えば、バグ報告や質問・要件定義・仕事しているアピール・人間との会話などに使えます。それと:+1:や:-1:をつかってバトルもできるようです。

そのようなissue機能ですが、ここではissueというものがどのような方法で作成されたり編集されたりするのかを考えてみます。まず一番に思いつくものであり、我々がよくやる方法が、ブラウザ上でマウスなどをつかって作成や編集などをやるというものです。この方法は手軽ですが、私は何かもっと効率的な方法でissueを編集できたらいいのにという感情になることもあります。

そこで、次に思いつくのがAPIを叩くというものです。GitHubやGitLabはソフトウェア開発者を利用対象者としていることもあってAPIは充実しているようです。APIがあればほとんどの操作をブラウザを開かずに行えます。しかし、なにかしらのコマンドラインツールを通して生のAPIを叩くだけでは、結局、1つ1つissueを作成したり編集したり開けたり閉めたりと、ちまちまとしたことをやっていく必要があります。

DiffissueではData Driven的にissueを管理することによってこの問題を解決します。我々がするべきことはVimなどのエディタを使って作りたいissueをファイルに書き込むことだけです。あとの仕事はすべてDiffissueくんがやってくれます。自動でissueを作成してくれますし、Diffissueという名前にも含まれているように、issueデータのdiffを取った上でタイトルや説明文の更新やissueの追加、削除なども自動で行われます。

「いや、でもそこまでする必要ある?さらに面倒くさくなるだけじゃない?」という意見もあると思いますが、全くそのとおりだと思います。ただバグ報告や質問をするためだけのために、わざわざissue定義ファイルを編集するということはできればやりたくないです。しかし、Diffissueが必要とされるようなissueの使用方法もあります。何かしらの元データがあってそれを使ってissueを作成したい場合です。最初の方での例にもだした要件定義などがそうです。要件定義をファイルに書き出したあと、それをそのままissueにすることができますし、要件の追加・削除・編集もファイルに書けば、あとはDiffissueが自動でやってくれます。

どんな感じで使うか

本来はここでDiffissueのインストール方法やコマンドラインツールの使用方法などを解説するべきだと思いますが、Diffissueは昨日はじまったプロジェクトなので、まだ簡単なインストール方法が用意されていなかったり、コマンドが必要最低限の機能しか持っていなかったりします。以上の理由からここではどのような雰囲気で使うのか軽く説明するだけに留めます。

issueの定義は以下のようなmarkdownで行います。

# Add support of related issues
- [ ]  Write a test
- [ ]  Implement

# Write README
It requires some sections,
overview, installation, usage, and customization.

ファイル名が1.mdだったら、

diffissue --project ryo33/test --token $ACCESS_TOKEN 1.md

とするだけで自動でissueが作成されます。

issueの追加や削除、編集などを行いたい場合は新しいissue定義ファイル(ここでは2.mdと想定)を作って

diffissue --project ryo33/test --token $ACCESS_TOKEN 1.md 2.md

とすれば自動で更新されます。

おわり

終わりです。今後もっと便利になっていきます。Citadel Xプロジェクトで使用しようと思っています。

Written on July 31, 2018