2013/6/16追記
docrailsがrails下に置かれるようになりました。
http://weblog.rubyonrails.org/2013/6/14/docrails-back-to-the-roots/
昨日edge railsの小さなコメント修正漏れに気づいて
Pull Request #7852を送ったら、すぐ取り込まれました。
よくよく考えると、コメントの修正だけだから
docrailsでも良かったんじゃないかなと思って
docrailsのリンク先にあるこの記事を見直してみた。
Riding Rails: What is docrails?
docrails概要
・Railsのドキュメントを簡単にメンテナンスするためのリポジトリ
・masterを修正すればOK
（pull request不要。自信が無いならRailsへpull requestでもOK。）
・誰でも修正可。（Railsにmergeされる前にレビューされる）
・数日おきにRailsのmasterへmergeされる
・ソースの修正はNG
・ack -a 結構便利
(brew install ack // perlのモジュールなんですね)
記事の意訳（機械翻訳っぽくなっちゃった）
What is docrails?
docrailsは、Railsのブランチで誰でもdocの修正をpushできるものです。
もしtypoを見つけたり、事実に基づく間違いの修正、存在するドキュメントの補足、
有用なexampleの追加をしたい場合、docrailsが存在する以前は、pull requestを送り、
通常のワークフローで承認されなければならなかった。
docrailは、リポジトリをclone、修正、pushまでできるようにしたものです。Done!
ZOMG, that's awesome! Tell me more!
code baseへの変更は、pushする前にレビューが必要となります。
個々の新機能やバグフィックスは、決定権のあるcore teamメンバーの理解や責任が
必要となります。
しかしながら、ドキュメント修正については、もっとより良い方法がありそうです。
という考えから、docrailsは、contributorのワークフローを簡単にするために
public writeなポリシーを持っています。
すべてのcommitはどこかでレビューされなければなりません。
だからdocrailsは、pull requestを通して行っているものより
Railsコミッターから同じ労力を必要としています。
ですからみなさん、最近ではこの時間のかかる作業をしているVijay Devの
大きな支えとなってください。
docrailsのポイントは、contributorのために早く簡単に
Railsドキュメンテーションへcontributeする方法を提供することです。
But wait, I am editing some separate thing?
docrailsは、別の異なるアクセスポリシーを持つため、別のブランチにしています。
しかし、実際にはRailsドキュメンテーションなのです。
数日おきに、すべての新しいコミットはレビュー後にdocrailsはmasterへマージされます。
そして、masterはdocrailsへマージされます。
また、大きな重要な修正は、マージする人の裁量でstable branchへcherry-pickされます。
What is allowed in docrails?
自由に全てのRDoc、guides、READMEsを修正してpushできます。
コードの修正はしないでください。重要なルールです。
どんなに些細な、1文字のtypoでさえです。
CHANGELOGは修正することができません。
Is docrails a documentation project?
いいえ、Railsはドキュメンテーションプロジェクトを持っていません。
プロジェクトの別の側面としてドキュメンテーションを取り扱っていることは
プロジェクトの外部部分としてテストを扱うことと同様でしょう。
ドキュメンテーションはRailsの必要不可欠な部分です。
機能やバグフィックスのcontiributingは、そのコードやテストやドキュメンテーションを
contiributingするということなのです。
I am preparing a pull request, should I document later via docrails?
いいえ、docrailsは簡単なドキュメント修正のみのものです。
pull requestは完全であるべきです。：コード、テストそしてドキュメント。
もし、それらのいずれかを欠いている場合、一般的には受理されないでしょう。
また、ドキュメントの更新するということは、あなたが編集しているそのコードの隣のRDocを
編集するという意味では有りません。
しばしば、その変更が、そのpull requestが何についてのインスタンスかを探すために
プロジェクトtreeをgrepすることを必要とします。
あなたの修正によって影響を受けた、例の更新や、説明の改訂
または、新しいドキュメントを書く必要があります。
Tidbit: "ack -a"を実行するとガイドを含めた検索をすることができる
I made a doc fix, when is it going to be online?
Railsのリリースはcopmlete setです。
ドキュメンテーションはリリースの一部です。
修正を含むブランチがリリースされたとき、Stable API or guidesのウェブサイトで見れます。
masterにマージされた修正は、masterにpushされた後再作成された
edge API and edge guidesでいつでも見れます。
このようにして、docrailsを通して修正は、次のdocraisl/master がcross-mergeされた後
edge docsで見ることができます。
Can I open pull requests for documentation fixes in Ruby on Rails?
もちろん。特にその修正に自信が無ければ。
もし自信があれば、docrailsにpushしてください。
docrailsではpull requestをopenしないでください。
docrailsはissues機能を持っていません。理由はdocrailsはプロジェクトでないからです。
上記で説明したようにpull requestを迂回する方法だからです。
ドキュメンテーションのissuesはRailsのissueであり、
他の種類のissue同様Railsプロジェクトに属しています。
Does Ruby on Rails has documenters?
いいえ。ドキュメンテーションはmasterへのpushに付属するものです。
みんながRailsのドキュメントをメンテナンスするのです。
唯一の例外は、guideの筆者です。
guideの筆者は特定topicについて、丸々新しいガイドを書くというタスクを実施します。
便宜上docrailsに草稿をpushすることが許されています。
それは新しいガイドにだけ適用されています。一度公開されると、guideのメンテナンスは
他の全てのものと同様masterで行われます。
おまけ
ack -a
