Octaccord Technical Memo

Introduction

これまで GitHub + Redmine でプロジェクト管理をしていた． Redmine のチケット管理は強力だが，GitHub に置いたコードとの連携が弱い． GitHub issue でコードに関する議論やレビューをしたいので， Redmine との行ったり来たりが面倒になる．加えて Redmine のサーバを自前でサーバを持つのが重荷．このさい，GitHub だけで管理できないのか．

そこで，GitHub + GitHub Wiki でプロジェクト管理を試みてみた．足りない部分を支援する簡単な CLI ツールを作成した．

Related Works

GitHub によるプロジェクト管理についての既存の試み．

共通としているところは，

Milestone を Scrum の Sprint として活用
Product Backlog (PBL) をどう管理するのかは曖昧．別途ツールを用意している? (Excel や Google Docs)

GitHub + Wiki だけで困りそうな事は，

PBL の (優先順位) の管理
Github Wik の貧弱さ

GitHub の問題点

Task (issue) の状態管理

Todo, Doing, Done
締切，進捗(パーセント)，コスト(負荷)

統計情報の提示

各人の抱えている issue 数(負荷)
各人のこなした issue 数
現状のグラフは，モチベーション向上につながっていないのではないか

Issue の自動分類

スマートフォルダのようなイメージ．以下のような issue を瞬時にリストアップできるようにラベルを自動で貼る．

最近更新がない
重要 (基準は，まだ曖昧 comment の量が多いなど?)
プルリクエスト(PR)が付いている
階層の上(下)にある
今イテレーションで解決が必要
締切に遅れている
プロダクトバックログに入るべき

Issue の並べ変え(優先順位付け)

現状存在するのは，

newest, oldest, recently updated, least recently updated, most commented, least commented

他にもあると便利そうなのは，

期限が迫っている順
プルリクエスト (PR) が付いている順
任意の順番の定義 (Product Backlog を issue で管理するなら必須)

Issue と PR の関係を提示

現状のインタフェースでは，話の流れを追いかけ辛い
PR が付いている元 issue の一覧
- rails/rails の attached PR というラベルが，それを指向していたように見えるが，管理されていない
Issue 間のグラフを見る → 檀上のテーマの一部

議事録作成支援

会議中に issue について付いたコメントの一覧をイテレーション記録として wiki に残したい

プロダクトバックログ (PBL) の管理

特定のラベルの付いた issue を PBL とみなす?

対処

PBL Issue 一覧を取得して PBL Wiki Page を自動作成する

コマンド書式

octaccord backlog nomlab/LastNote --label=PBL --replace LastNote.wiki/Product-Backlog.md

出力結果

Product-Backlog.md 中の

<!-- octaccord:begin backlog -->
...
<!-- octaccord:end backlog -->

で囲まれた部分に，プロダクトバックログのテーブルを埋める．書式は，以下の通り．

No.	Title	Story	Demo	Cost
#100	招待機能の実装	メンバとして，ML にメールを投げることでイベントの出欠を簡単に取りたい．それは，イベントの開催を活発にしたいからである．	gn メーリングリストに送信する際にアドレス末尾に「+inv」と追記して送信すると，LastNote 上に対応するイベント参加者一覧のページが作成される．メンバに届いたメール本文には，イベント出欠を返答するリンクが付いている．出席/欠席のどちらかをクリックすると，出欠一覧ページに出欠状況として名前が反映される．	5

No: PBL Issue の番号 [#100](../issues/100) のように Issue へのリンクにする．
Title: PBL Issue のタイトル
Story: PBL Issue の記述中の # Story 以下の記述を抜き出してきたもの
Demo: PBL Issue の記述中の # Demo 以下の記述を抜き出してきたもの
Cost: 実装するのにかかるコストを示す整数(空欄でよい)

ただし，既にテーブルがある場合は，以下の状態を保存する

No. と Cost の値
ソート順

既存の既にテーブルになかった新規の PBL Issue は，末尾に追記する．

指定された PBL Issue の内容から Task Issue を作成する

コマンド書式

octaccord create-task nomlab/LastNote --label=PBL --add-label=Itr0094 100 111 ...

各引数の PBL Issue について
description か comment から # Tasks 以下の項目を抜き出す (末尾の # Tasks を優先する)
子要素である各 ## title... 項目を Task Issue として新規作成する．
Task Issue の本文中に，元となる PBL Issue への参照を入れる．(#100 のように)
元となる Issue の # Task 以下の ## title... 部分を ## #150 title... のように置き換えておく．
2度，同じ操作をしても，新規に作成しないように， title 部分が #番号 で始まる部分は，無視すること．
-add-label で指定された label を作成した Task Issue に付けること．

Floating Issue を発見してラベルを付ける

Story

マネージャが，重要なラベルの付いていない Task Issue にラベルを付けたい．それは，棚卸すべき Task Issue が何であるかを素早く確認したいからである．

コマンド書式

octaccord update-label nomlab/LastNote --search='!label:/^[A-Z]/' --label=Floating
# 現状，こう書けば一応できる?↓
octaccord scan nomlab/sandbox --search="no:milestone -label:PBL" --format=number |\
  xargs octaccord update_issues nomlab/sandbox --labels=Floating

大文字で始まるラベルは，排他的に付けられることが前提
全ての Issue について， --search 式にマッチした Issue のみに --label で指定されたラベルを付与する．
つまり，マッチしなかった Issue からは，ラベルをはがすことも必要．

検索式に一致する Issue を列挙する (未完)

コマンド書式

octaccord issues nomlab/LastNote --search="!label:"

ある時刻の範囲でアップデートがあった
ある時刻の範囲で作成された
あるラベルにマッチする/しない
オープン/クローズの別

Wiki Page 中の Issue 番号に反応して最新の情報を付与する

コマンド書式

octaccord embed-issue-info nomlab/LastNote --replace Itr0094.md

Wiki のページ中に現れる #番号 の記述をスキャンして，リンクやタイトルを付与する．

#番号 の記述にリンクを付与して， [#番号](../issues/番号) の記述に置き換える
行頭の * や # の直後に来る場合は後ろに Issue のタイトルも追加する

この機能によって，Wiki 中に

* #150

とだけ書いておけば，リンクとタイトルが付いた記述に置き換えられる．

* =[#番号](../issues/番号)= カレンダをまたぐリカーレンスを作成できないようにする

付けるべきラベルの一覧

PR には，ラベルを PRは， issue の付属物として見る．大文字で始まるラベルは排他的にしかつかない．

PBL: プロダクトバックログ相当の issue に付けるラベル．各イテレーションの開始時の会議で付けられる． octaccord は，PBL Wiki に当該 issue を追加する．
ItrXXXX: イテレーション内で消化すべき issue に付けるラベル．各イテレーションの開始時の会議で付けられる． (Scrumでいうスプリントバックログ) 同一の名前でマイルストーンが設定される． close されたものから，自動的に剥されていく．マイルストーンの期間が過ぎると label は消滅する．
Floating: PBL でも Itr のどちらも付いていない issue．
pullrequest: レビューが必要な (PRが付いた) issue
incomming: 前イテレーション中に付いた新規の issue
updated: 今Itrで更新されたため，議論が必要なissue
unbound PR: どの issue にも関連しない PR
stale: 一定期間更新のない issue

ラベル付けの手順

状態に関するラベル (PBL, ItrXXXX, Floating)

全ての open issue について

pull_request なら，終了
label:PBL なら，終了
label:Itr???? を全部剥がす octaccord label –search=”type:issue -label:PBL” –remove=”^Itr.*” –add=”%milestone||Floating”
ms:Itr???? なら，同名の label を付け終了
label:Floating を付け終了

全ての open issue について

created: ItrXXXX の Due Date の後で ItrYYYY の Due Date より前なら，label:incoming を付ける octaccord label –search=”created:<{-7days}” –add=”incoming” –exclusive
updated: が 1ヶ月前以上なら label:stale octaccord label –search=”updated:<{-30days}” –add=”stale” –exclusive
他の pull_request の body 中に自身の issue 番号があるなら， mentioned を付ける octaccord label –search=”mentioned” –add=”mentioned” –exclusive
pull_request で，どの issue にも言及していないなら，unbound を付ける octaccord label –search=”type:pr is:referred” –add=”unbound” –exclusive

人間によるラベルの処理

PBLの処理

User Story を最初に述べる
Tasks から始まる章は Issue にする
Issue を作成したら， Issue 名の後ろに作成した Issue 番号を追記する
作成する Issue から，基となる PBL の Issue を reference する．

Issue を Review 後の処遇

次のItr番号を付与．
プロダクトバックログ化
close
Itr番号を単に外す．

勉強

GitHub API

参考URL

https://developer.github.com/guides/ (まずこれを読む)
https://developer.github.com/v3/ (API リファレンス)
https://help.github.com/categories/78/articles (search)
https://developer.github.com/v3/markdown/ (Markdown レンダラ)

API のクライアント実装

issue と pull の違い

# issues として取得
curl -s -i -u yoshinari-nomura https://api.github.com/repos/nomlab/LastNote/issues/113 > attic/i113
# PR として取得
curl -s -i -u yoshinari-nomura https://api.github.com/repos/nomlab/LastNote/pulls/113 > attic/p113

両者は，同じモノのようだが，返って来る情報が違う

ETag は，両者で異なる (これは当然)
id が両者で異なる (これは意外)
body は，同期している

以下は，issue にしかない

labels
events

一方，merge や commit 関連の情報は pulls にしかない．また，HTML URL を開くと，pull にリダイレクトされる． https://github.com/nomlab/LastNote/issues/113 は https://github.com/nomlab/LastNote/pull/113 へリダイレクトされる

issue の updated_at は，いつ変化するのか

label を付けかえるだけで変化する
comment の変更でも変化する
タイムスタンプを頼りに何かをするのは，難しそうだ

issue に関する議論は，コメントで付けて，会議の議事録に抜き出して Wikiに追記するのは，抜き出す基準が時刻になるので，難しい．その場でならいいが，後日抜こうとするとダメかといって，issue コメントに会議の場で付いたコメントを示すマークを付けるのは，面倒だ．

検索

API では，「PBLラベルを含まない」に対応するのは -label:PBL のように - を付ける

curl -s -u yoshinari-nomura 'https://api.github.com/search/issues?q=Tasks+label:PBL+-label:management+repo:nomlab/LastNote'| less

なぜか，issue のコメント欄が検索にヒットしない． https://help.github.com/articles/searching-issues#search-in の in:comment がうまく働かない?

curl -s -u yoshinari-nomura 'https://api.github.com/search/issues?q=Tasks+label:PBL+repo:nomlab/LastNote+in:comment'| less

Github Wiki (Markdown)

Octkit

https://github.com/octokit/octokit.rb

用語

Elevator Pitch

エレベーター(elevator)に乗っている間に説明(pitch)できるような売り文句．たとえば， このシステムは，[]したい[]向けの[]という名前のシステムは，[]です．これは，[]ができ，[]とは違って，[]が備わっています． のような短かい文言．

Product Backlog

製品で実現すべき機能の一覧に優先順位を付けたもの
常に更新や追加され，順番の並べ変えが置こる
各項目にコストの項目が付く
- コストは具体的に作業が想像しやすいものを基準にして相対的に値を付ける
- フィボナッチ数で相対値を決めることで，微妙な数の違いを付けられなくするとよい大きな違いを発見することで，分割すべきかどうかの判断の助けとなる．
ユーザストーリーの形で書くことが多い

スプリント

イテレーションとほぼ同義
最長1ヶ月程度の期間
計画，設計，開発，テストのプロダクトのリリース判断に必要な内容を実施する．
期間は，延長しない．タイムボックスを守る(短縮は，可能)．

Technical Memo - nomlab/octaccord GitHub Wiki

Octaccord Technical Memo

Introduction

Related Works

GitHub の問題点

Task (issue) の状態管理

統計情報の提示

Issue の自動分類

Issue の並べ変え(優先順位付け)

Issue と PR の関係を提示

議事録作成支援

プロダクトバックログ (PBL) の管理

対処

PBL Issue 一覧を取得して PBL Wiki Page を自動作成する

コマンド書式

出力結果

指定された PBL Issue の内容から Task Issue を作成する

コマンド書式

Floating Issue を発見してラベルを付ける

Story

コマンド書式

検索式に一致する Issue を列挙する (未完)

コマンド書式

Wiki Page 中の Issue 番号に反応して最新の情報を付与する

コマンド書式

付けるべきラベルの一覧

ラベル付けの手順

状態に関するラベル (PBL, ItrXXXX, Floating)

人間によるラベルの処理

PBLの処理

Issue を Review 後の処遇

勉強

GitHub API

参考URL

issue と pull の違い

issue の updated_at は，いつ変化するのか

検索

Github Wiki (Markdown)

Octkit

用語

Elevator Pitch

Product Backlog

スプリント

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️