[PR]
ドキュメントについてつらつら
* 全員が知っておかなければならない(MUST)情報
** ただし他のドキュメントで事前に得うる情報
** このドキュメントでしか得られない情報
* 全員が知っておくべき(SHOULD)情報
* 知りたい人が知っていればよい(MAY)情報
ドキュメント内は例えばこんな風に分類することもできると思っていて、
これをいかにして必要十分に書くかという話。
ある程度の網羅性は必要。
しかし冗長すぎると誰も読まない。
抽象化しすぎると分かりにくい。
読む人のバックグラウンドの違いによる誤解を防がないといけない。
☆MUST,SHOULD情報をいかに簡潔に書くか
これは流し読み5分で大体解るようにしたいなぁ。
必要なら、別冊クイックスタートガイドのようなものを作る。
MUSTの「他のドキュメントで事前に得うる情報」を、「最低限のことはこのドキュメントを読めば解る」＋「さらに詳しいこてとは他のドキュメント(参照)へ」に分ける。
なるべく一ドキュメントで完結させる。「他のドキュメントに書いてあるからそっち読め」っていうのは参照のチェーンができちゃうので極力避けるべき。
具体例だけを示すのは賢いやり方ではない。具体例を示すとき、可能ならば二例以上示した方がよい。
具体例はあくまでも「ある一点の説明」であって、それだけではそれ以外の点がどうなのか推測できないから。
例えば、「5を入力すると10を返す機能」とだけ説明された時、「入力された数よりも大きい5の倍数を返す機能」とか「15と入力された数の差を返す機能」とか解釈する人もいるかもしれない(普通そんな解釈しないけど、極端な例として)。
「入力された数を2倍して返す機能。例えば5を入力すると10を返す」と説明すれば、先の例より誤解釈が減ると思う。
SHOULDかMAYかの線引きが一番難しいのかもなぁ。
** ただし他のドキュメントで事前に得うる情報
** このドキュメントでしか得られない情報
* 全員が知っておくべき(SHOULD)情報
* 知りたい人が知っていればよい(MAY)情報
ドキュメント内は例えばこんな風に分類することもできると思っていて、
これをいかにして必要十分に書くかという話。
ある程度の網羅性は必要。
しかし冗長すぎると誰も読まない。
抽象化しすぎると分かりにくい。
読む人のバックグラウンドの違いによる誤解を防がないといけない。
☆MUST,SHOULD情報をいかに簡潔に書くか
これは流し読み5分で大体解るようにしたいなぁ。
必要なら、別冊クイックスタートガイドのようなものを作る。
MUSTの「他のドキュメントで事前に得うる情報」を、「最低限のことはこのドキュメントを読めば解る」＋「さらに詳しいこてとは他のドキュメント(参照)へ」に分ける。
なるべく一ドキュメントで完結させる。「他のドキュメントに書いてあるからそっち読め」っていうのは参照のチェーンができちゃうので極力避けるべき。
具体例だけを示すのは賢いやり方ではない。具体例を示すとき、可能ならば二例以上示した方がよい。
具体例はあくまでも「ある一点の説明」であって、それだけではそれ以外の点がどうなのか推測できないから。
例えば、「5を入力すると10を返す機能」とだけ説明された時、「入力された数よりも大きい5の倍数を返す機能」とか「15と入力された数の差を返す機能」とか解釈する人もいるかもしれない(普通そんな解釈しないけど、極端な例として)。
「入力された数を2倍して返す機能。例えば5を入力すると10を返す」と説明すれば、先の例より誤解釈が減ると思う。
SHOULDかMAYかの線引きが一番難しいのかもなぁ。
PR
[FA]無題
遠くから汽車が走る音が聞こえる。
巡っているはずの星の下を、音も無く雲が滑っていく。
満月に一つ足りない月が、白く白く輝いている。
「——」
エドワードは古書から顔を上げた。
どこからか、歌が聞こえたからだ。
「誰だろうね。こんな深夜に」
アルフォンスがそう言って、少しガタつく窓を開けた。
夜気が床に溜まった埃と混ざる。
常夜灯がいくつか灯っているだけで、通りに人の姿は見えなかった。
月光に溶けていくような澄んだ歌声は、その出処を明かさない。
「綺麗だなぁ」
頁に栞を挟み、エドワードもアルフォンスに並んだ。
なんとか聞き取れる詞は、綴りの教本に載っていそうなほど素朴で。
ひたすらに素直な展開と音節毎に長く伸びる旋律は、聖歌を思わせた。
「歌姫は毎夜祈りの歌を歌い、国を守る、か——」
「あぁ、あったね。そんな昔話」
遠い思い出。
小さな箱にしまって置いてきたように思えて、実はどこまでも持ってきているもの。
無論歌い手は、エルリック兄弟が聴いていることを知らないだろう。
誰に届かせようとしているのかは、兄弟には分からない。
拡散する歌声の、空気との境界に、光のように純粋な感情が振動し、共鳴しているような気がするだけだ。
「この人も、何かを祈ってるのかな」
歌がループする。
目蓋を透かす月光を感じながら、エドワードは応えた。
「さぁ、な」
了
----------------------
あきの『歌姫』が大好きです。
巡っているはずの星の下を、音も無く雲が滑っていく。
満月に一つ足りない月が、白く白く輝いている。
「——」
エドワードは古書から顔を上げた。
どこからか、歌が聞こえたからだ。
「誰だろうね。こんな深夜に」
アルフォンスがそう言って、少しガタつく窓を開けた。
夜気が床に溜まった埃と混ざる。
常夜灯がいくつか灯っているだけで、通りに人の姿は見えなかった。
月光に溶けていくような澄んだ歌声は、その出処を明かさない。
「綺麗だなぁ」
頁に栞を挟み、エドワードもアルフォンスに並んだ。
なんとか聞き取れる詞は、綴りの教本に載っていそうなほど素朴で。
ひたすらに素直な展開と音節毎に長く伸びる旋律は、聖歌を思わせた。
「歌姫は毎夜祈りの歌を歌い、国を守る、か——」
「あぁ、あったね。そんな昔話」
遠い思い出。
小さな箱にしまって置いてきたように思えて、実はどこまでも持ってきているもの。
無論歌い手は、エルリック兄弟が聴いていることを知らないだろう。
誰に届かせようとしているのかは、兄弟には分からない。
拡散する歌声の、空気との境界に、光のように純粋な感情が振動し、共鳴しているような気がするだけだ。
「この人も、何かを祈ってるのかな」
歌がループする。
目蓋を透かす月光を感じながら、エドワードは応えた。
「さぁ、な」
了
----------------------
あきの『歌姫』が大好きです。
間違えちゃったら git reset and git revert で黒歴史削除
commit した後でそれを取り消したいとき。
まだremoteリポジトリへpushしてないなら、localで
$ git reset --hard HEAD~{n}
とすればHEADから{n}個分の commit を取り消すことができる。
"git reset --hard HEAD~3"で3個分。
で、問題はremoteにpushしちゃった後で取り消したくなったとき。
そう、git revertですね。
まずはlocalでrevert
普通にやるなら
$ git revert {取り消したい commit ID}
でいけるはずなんですが
別ブランチをmergeしたcommit だったり、別のリポジトリをsubtreeとして取り込んだ("git merge -s subtree_name"した)commit だったりしたときがまた。。
単純に先のコマンドを打つと
fatal: Commit (取り消したいcommit ID) is a merge but no -m option was given.
「このコミットはmergeなんだけど、-mオプションついてないよ」
って言われちゃいます。
で、-mオプションってなんぞ？ってわけで調べると"-m parent-number"とのこと。
parent-numberってなんぞ。。。と思ってえろい人に訊いてきました。
どうも、そのコミットに繋がってる(祖先、つまり親の)コミットの番号のようです。
それがmergeによってこうなってると
mergeしたcommitは、"git log"すると親を見ることができて
commit C
Merge: B Y
Author: hogehoge
で、書いてある順番に1,2,...とparent-numberが振られているみたい。(Bがparent-number:1,Yは2)
なので、Bの状態に戻したいときは
$ git revert -m 1 C
とすればよいようです。
で、"git log"等でうまくいったことを確認したら、remoteにpushすればOKと。
はーもうremoteリポジトリいじるの怖い。。
まだremoteリポジトリへpushしてないなら、localで
$ git reset --hard HEAD~{n}
とすればHEADから{n}個分の commit を取り消すことができる。
"git reset --hard HEAD~3"で3個分。
で、問題はremoteにpushしちゃった後で取り消したくなったとき。
そう、git revertですね。
まずはlocalでrevert
普通にやるなら
$ git revert {取り消したい commit ID}
でいけるはずなんですが
別ブランチをmergeしたcommit だったり、別のリポジトリをsubtreeとして取り込んだ("git merge -s subtree_name"した)commit だったりしたときがまた。。
単純に先のコマンドを打つと
fatal: Commit (取り消したいcommit ID) is a merge but no -m option was given.
「このコミットはmergeなんだけど、-mオプションついてないよ」
って言われちゃいます。
で、-mオプションってなんぞ？ってわけで調べると"-m parent-number"とのこと。
parent-numberってなんぞ。。。と思ってえろい人に訊いてきました。
どうも、そのコミットに繋がってる(祖先、つまり親の)コミットの番号のようです。
とコミットが連なっているとき、Cのコミットの親はBで、1つしかありません。A-B-C-D-...
それがmergeによってこうなってると
親がBとYの2つなので、どっちの状態に戻したいのか指定しないといけないと。A-B-C-D-...
X-Y/
mergeしたcommitは、"git log"すると親を見ることができて
commit C
Merge: B Y
Author: hogehoge
で、書いてある順番に1,2,...とparent-numberが振られているみたい。(Bがparent-number:1,Yは2)
なので、Bの状態に戻したいときは
$ git revert -m 1 C
とすればよいようです。
で、"git log"等でうまくいったことを確認したら、remoteにpushすればOKと。
はーもうremoteリポジトリいじるの怖い。。
githubでpermission denied(publickey)だにょ
んーってなったけど結局official siteに従ったら解決。
本家大事。。
原因はssh認証エージェントがgithub用に作った鍵を認識してなかったからっぽい。
.ssh/config でgithubにつなぐときに使う秘密鍵を指定
多分これでいけた。
sshで使う鍵の作り方
https://help.github.com/articles/generating-ssh-keys
ssh-keygenするだけかと思ったらオプションつけてねとあった。
よくわかんないけどid_rsaを見にいくようになってるのかなー？
githubにsshできないときのヘルプ
https://help.github.com/articles/error-permission-denied-publickey
portは22だよとかuserはgitだよとか
ヘルプに従ってssh-add -l したら、
自分の環境ではid_rsaがないからか、最初に作ったさくら用の鍵だけ登録されてました。
いろんな鍵つかうのでid_rsa以外の名前で作りたいんだけど。。
ちなみに間違ってssh-addしちゃったときはssh-add -d 消したい鍵 でいける。
[追記 2012/08/22]
新しくterminal起動したらそっちではまたpremission deniedになっちゃってなんでやねん！って3hくらい
また格闘してたんですけど、どうもssh-addは根本解決じゃなくって(ssh-agentが再起動されるとまた初期化されるようなので)
というか.ssh/configの書き方がよくなかったみたいです。
Host github
HostName github.com
....
としてたんだけど、git pullとかするとき、gitは"ssh git@github.com"のような感じで接続しようとするらしく、
でもってssh-agentは"ssh username@hogehoge"のhogehogeとHostが一致したらHostNameへ接続するようにしているようなので、
Host github.com
HostName github.com
....
としないと駄目なのでした。
ちなみにherokuも同じようにHost heroku.comにしないと駄目でした。
('・ω・`)
[さらに追記 2012/10/16]
githubの公式ヘルプには、ssh-keyをちゃんと登録できたかの確認で
ssh -T git@ssh.github.com
やってごらんとかありますが、id_rsaじゃないkeyを登録した場合は、configに
Host ssh.github.com
HostName ssh.github.com
IdentityFile ~/.ssh/hoge_rsa
....
って書くか、
ssh -T git@ssh.github.com -i ~/.ssh/hoge_rsa
ってするかしないといけないみたい('・ω・`)
まぁ、一回しか使わないんで後者のが楽ですね。
ちなみに、このとき-vオプションつけるとデバッグ用にログが出るので、何が起きてるか分かりやすいデス。
(sakura絡みでどっかに書いたような気がしなくもないけど。)
本家大事。。
原因はssh認証エージェントがgithub用に作った鍵を認識してなかったからっぽい。
ssh-add github用に作った秘密鍵の絶対パス
.ssh/config でgithubにつなぐときに使う秘密鍵を指定
sshで使う鍵の作り方
https://help.github.com/articles/generating-ssh-keys
ssh-keygenするだけかと思ったらオプションつけてねとあった。
よくわかんないけどid_rsaを見にいくようになってるのかなー？
githubにsshできないときのヘルプ
https://help.github.com/articles/error-permission-denied-publickey
portは22だよとかuserはgitだよとか
ヘルプに従ってssh-add -l したら、
自分の環境ではid_rsaがないからか、最初に作ったさくら用の鍵だけ登録されてました。
いろんな鍵つかうのでid_rsa以外の名前で作りたいんだけど。。
ちなみに間違ってssh-addしちゃったときはssh-add -d 消したい鍵 でいける。
[追記 2012/08/22]
新しくterminal起動したらそっちではまたpremission deniedになっちゃってなんでやねん！って3hくらい
また格闘してたんですけど、どうもssh-addは根本解決じゃなくって(ssh-agentが再起動されるとまた初期化されるようなので)
というか.ssh/configの書き方がよくなかったみたいです。
Host github
HostName github.com
....
としてたんだけど、git pullとかするとき、gitは"ssh git@github.com"のような感じで接続しようとするらしく、
でもってssh-agentは"ssh username@hogehoge"のhogehogeとHostが一致したらHostNameへ接続するようにしているようなので、
Host github.com
HostName github.com
....
としないと駄目なのでした。
ちなみにherokuも同じようにHost heroku.comにしないと駄目でした。
('・ω・`)
[さらに追記 2012/10/16]
githubの公式ヘルプには、ssh-keyをちゃんと登録できたかの確認で
ssh -T git@ssh.github.com
やってごらんとかありますが、id_rsaじゃないkeyを登録した場合は、configに
Host ssh.github.com
HostName ssh.github.com
IdentityFile ~/.ssh/hoge_rsa
....
って書くか、
ssh -T git@ssh.github.com -i ~/.ssh/hoge_rsa
ってするかしないといけないみたい('・ω・`)
まぁ、一回しか使わないんで後者のが楽ですね。
ちなみに、このとき-vオプションつけるとデバッグ用にログが出るので、何が起きてるか分かりやすいデス。
(sakura絡みでどっかに書いたような気がしなくもないけど。)