=encoding utf8

=pod

=head1 題名

Moose::Manual::Contributing - Mooseの開発に加わるには

=head1 開発に加わる

Mooseはオープンなプロジェクトです。バグフィックスや追加のテスト、ドキュメントのパッチはいつでも大歓迎です。コミット権も惜しみなく与えられますし、L<基本ワークフロー>もシンプルです。作業の基本は簡単です： gitリポジトリからコピーをクローンし、トピックブランチでハックした後、内容をコミッタの人に確認してもらうだけです。

=head2 IRCとメール

IRC上ではB<多くの>議論がかわされています。irc.perl.orgには#mooseと#moose-devという2つのチャンネルがあります（#mooseの方がはるかに活発ですが、コア開発者は両方のチャンネルに目配りしています）。

また、メーリングリストもあります(moose@perl.org)。コア開発者は全員リストのメッセージを読んで返事をしています。

=head1 新しい機能について

Mooseはすでにかなり大量の機能がありますから、いまのところ新たに重要な機能を追加する予定はB<ありません>。Mooseに新しい機能を追加したい場合は、まずはそのかわりにMooseXモジュールを作ることをおすすめします。

いまの段階では、先にMooseXモジュールという形で十分に吟味されていない機能については、新機能としてコアに追加しようという話にすらなりません。コアに入れない限り絶対に100％実装不可能な機能であれば話は別ですが。

本当に100％不可能と考えるのであれば、それについてIRCかメールで議論してください。コアに小さなフックが必要だったり、コアモジュールの一部をリファクタリングする必要はもちろん検討します。

Mooseは最初から非常に拡張性を重視して作られてきました。新機能の要望が寄せられても、たいていはよくできた小さな拡張モジュールをいくつか使えば実装できてしまうものなのです。だから、まずはそちらを試してみてください。思っているよりはるかに簡単ですから。

=head1 関わっている人々

Mooseが成熟するにつれ、少しずつ体制も整ってきました。

=over

=item コントリビュータ - トピックやブランチを作成する人

これはあなたの事です。

もしすでにコミット権限を持っているなら、マスタのMoose.gitにトピックを作成してください。そうでない場合は、我々にあなたのSSH鍵を送ってもらうか、L<git://git.moose.perl.org/Moose.git>のクローンレポジトリを自前で作るかGithubのミラーをforkしてください。

=item コアコミッター - ブランチを確認・マージする人

彼らはMooseコードベースにある程度慣れた人たちです。

彼らは大きな機能変更やブランチの責任者をしていた人たちで、あなたのコードのレビューやマスターへの適用をL</承認ワークフロー>を通して行うことができます。

また彼らは間違いなくブランチをマージしたり、他のコントリビュータの手助けをする必要があるため、ある程度Gitに精通しているはずです。

=item 「中の人」- Mooseをリリースできる人たち

彼らはMooseのメンテナ権利を持ち、Mooseをリリースする事ができる人たちです。彼らはMooseドキュメント内のL<Moose/CABAL>に名前が記されています。MasterからStableへのマージは彼らが行います。

=back

=head1 ブランチ レイアウト

参加する皆様のためにMooseレポジトリのためにレポジトリは複数のブランチに分けられています。以下のブランチは安定度の順番に記されています：

=over

=item Stable (refs/heads/stable)

新規リリースが生成される元のブランチです。新規リリースを作成する時にリリース責任者がマスターからStableにマージを行います。このブランチはリリース責任者だけがリリース時にアップデートします。

=item Master (refs/heads/master)

新規開発用ブランチ。

=item Branches (refs/heads/*)

コミュニティによる変更や、大きなプロジェクトごとのブランチ。

=item Topics (refs/heads/topic/*)

rebaseされてもよい、レビューのためにパブりっしゅされた細かい変更・個人用ブランチ。数個のコミットで対応できる単位の変更等。

バグフィックス等はトピックブランチで行われるべきです。

=back

=head1 基本ワークフロー

    # update your copy of master
    git checkout master
    git pull --rebase

    # create a new topic branch
    git checkout -b topic/my-feature

    # hack, commit, feel free to break fast forward
    git commit --amend                       # allowed
    git rebase --interactive                 # allowed
    git push --force origin topic/my_feature # allowed

上記を行ったあと、変更点の確認および承認を行い（L</承認ワークフロー>参照）、その後マスターブランチにマージしてください。コンフリクト無くマージし、なおかつ誰も異議お唱えなければ、その後マスターブランチにプッシュすることができます。

もしマージがfast forwardとしてうまく行かない場合、ブランチ作者は以下のコマンドを走らせる必要があります：

    git remote update
    git rebase origin/master # or merge

このようにして手持ちのブランチを最新にアップデートした後、fast forwardマージとして処理する必要があります。

マスターブランチに対するマージを行う場合は人によるマージ（コンフリクトの解決）は行うべきではありません。マスターブランチから他のブランチにマージするときにのみ、行われるべきです。

=head2 トピックブランチの準備

マージの前にトピックブランチは作者によって「掃除」されます。

これはコミットを複合化する対話的なrebase等の手法や、C<git merge --squash>を用いてトピック全体を一つのコミットとすることによって行う事ができます。

このような変更点の複合化を行うことにより、後に問題が会ったときにgit revertなどを適用する際に便利になるほか、変更お途中途中で起こった細かい失敗等で履歴を汚すことなく作者の意図が履歴にきれいな形で残せるようになります（「ファイル入れ忘れ」のようなコミットは単に無駄な雑音というだけでなく、git bisectやgit revertを使用する際の妨げになります）

それ以上に一番の利点は、マスターブランチに入るコミットの中身をシンプルにし、コミット数そのものを減らせるということがあげられます。それにより、他のブランチの管理者が容易に最新コードを適用できるようになります。

また、大きな変更はL<Moose::Manual::Delta>にその内容が明記されるべきです。.

=head1 承認ワークフロー

Mooseはオープンなプロジェクトですが、問題発生時いはMooseが安定している事に依存する他のプロジェクトに多大な影響を与える可能性のある重要なプロジェクトでもあります。そのためブランチのレビュー・マージを行うための基本ワークフローが存在します。以下は全ての新規コードがmasterにマージされる前に正しい手順とレビューを通過することを義務づけるための大まかなガイドラインです。

重要な点は、特定のブランチを承認してほしい場合、このガイドライン及び作業が正しく行われているかどうか確認するのはB<あなた＞の責任であるということです。承認待ちのブランチの特定を容易にするために、メーリングリスト上でレビュー及び承認の依頼を行うことが推奨されます。

=over 4

=item 細かいバグ修正、ドキュメントパッチ、（パスする）追加テスト

これらは主立ったコントリビュータによるレビュー以外特に承認は必要ありません。

=item 大きめのバグ修正、新規ドキュメント、TODOもしくは失敗テストケース

大きめのバグ修正は必ず主だったコントリビュータによるレビューを行い、moose-dev-utilsレポジトリに登録されているF<cpan-stable-smolder>スクリプトを使用してテストしてください。

新規ドキュメントはいつでも歓迎ですが、主立ったコントリビュータに間違いがないか確認してもらってください。

TODOテストはすなわち新機能の要望ですので、詳細についてはL</新しい機能について>をご覧下さい。もしあなたの欲しい新機能がMooseコアへの変更を必要とするようならば、L</基本ワークフロー>を参照してコードを書いて下さい。

失敗テストケースはすなわちバグ報告です。主立ったコントリビュータにそれが本当にバグなのかどうか確認した後、RTキューにバグ内容とテストを投稿してください。レポジトリはバグ報告には向いていません。

=item 新規外部変更

ユーザーが直接触れることのできる外部仕様の変更はB<1人以上＞の主立ったコントリビュータによって承認される必要があります。

ガイドラインを正しく踏襲しているかどうか、L</新しい機能について>をよく確認してください。Mooseコアへの追加が拒否されても驚かないでください。

=item 新規内部変更

新規に追加されるMooseの内部機能についてはユーザが直接触れる機能よりも緩いですが、最低限B<1人>の主立ったコントリビュータによる承認が必要です。

その前にsmolderスクリプトを使用して他のMooseXモジュールなどに影響を与えていないか確認しておくのが理想的です。（他の人にではなく）あなた自身がこれを先に行う事によって、ブランチの承認が得やすくなるでしょう。

=item 後方互換性のない変更

後方互換性の無い変更を実装する場合はすべからく主立ったコントリビュータ達と議論を交わした後、彼らの多数がそれに賛成する必要があります。

MooseについてはL</後方互換性>についてのポリシーが存在します。もしあなたの変更が後方互換性を壊す場合はその変更についての追加議論、およびそれを弁護する準備をしておくのがよいでしょう。

=back

=head1 リリース ワークフロー

    git checkout master
    # edit for final version bumping, changelogging, etc
    # prepare release (test suite etc)
    git commit
    git checkout stable
    git merge master # must be a fast forward
    git push both
    # ship & tag

開発リリースの場合はStableへのマージは行いません。

=head1 緊急不具合 ワークフロー (即時リリース）

Stableブランチから派生ブランチを作成する事により修正を行えます：

    git remote update
    git checkout -b topic/my-emergency-fix origin/stable
    # hack
    git commit

その後、リリース責任者がStableにマージします：

    git checkout stable
    git merge topic/my-emergency-fix
    git push
    # release
    git checkout master
    git merge stable

=head1 プロジェクトワークフロー

寿命の長いブランチでは定期的にmasterがマージされるsubversionスタイルのブランチレイアウトを用います。ブランチ貢献者全員がC<git pull --rebase>を正しく使っている限りRebase処理は行ってもかまいません。

C<commit --amend>、 C<rebase --interactive>、 等はトピックブランチ以外では使用しないでください。masterへのコミットはトピックブランチと同じレビュー作業を通して行い、マージは必ずfast forwardとして行う必要があります。

大きめの変更に対するブランチでの作業は現在このように行われています。

当然技術的にはブランチの数には制限はありません。プロジェクトブランチからトピックブランチを生成したり、サブプロジェクトを親ブランチ内から生成するのは自由に行って下さい。間違えてmasterにマージされるのを避けるためにそれらのブランチは派生元のブランチの名前を使って生成されるべきです：

    git checkout -b my-project--topic/foo my-project

(残念な事にGitはC<my-project>が既に存在するとC<my-project/foo>の生成を許可しません)

=head1 "PU" ブランチ

寿命の長いブランチの管理を簡易にするため、'pu'ブランチでは全てのブランチをマスタにマージした場合の状態を保持しています。

このブランチは必要なときに定期的に更新され、マージに問題がある場合にはそれぞれのブランチ作者に連絡が行くようにしています。

'pu'ブランチをアップデートするために以下の手順がとられます:

    git checkout pu
    git remote update
    git reset --hard origin/master
    git merge @all_the_branches

もしマージがクリーンに適用できる場合はC<push --force>を使って'pu'ブランチがアップデートされます。

もしあるブランチのマージが適用できない場合、該当ブランチはコンフリクトがあった事を記録した上でC<@all_the_branches>から取り除かれます。

マージに失敗したブランチの作者は自分で'pu'ブランチへのマージを試みてどのような作用があるのか確認するべきです。

ほとんどの場合'pu'ブランチは壊れているでしょうが、それぞれ他のブランチがどのようにお互いと影響するかが確認できます。

=head1 ブランチのアーカイブ

マージされたブランチは削除されるべきです。

うまくいかなかったブランチは残しておいてもよいですが、git branch -l を最新の状態にしておくために refs/attic/ (e.g.  http://danns.co.uk/node/295) への移動を検討してください。

現実的にまだ近い将来にマージされる可能性のあるブランチはアーカイブするべきではありません。

=head1 テスト、テスト、テスト

MooseやClass::MOPにコードを追加する場合は「どんなコードであっても」そのコードに対するテストをB<書かなければなりません>。テストがない場合、本当にそれが正しい、求められている動作なのか確認する方法がありませんので、あとからその修正が削除されたり変更されたりしないと保証することはできません。

修正・追加したコードがMoose/Class::MOPの奥深くにあって、自明な形ではテストできない場合は、問題のコードの近くかテストの中にコメントを書いて、ほかの人にもわかるようにしておいてください。

また、コードの変更にあわせてドキュメントを書いたり、Changesファイルに変更点を載せたりしてもらえると非常に助かります。ご自分のお名前を書いておくのもお忘れなく！

=head1 後方互換性

変化が起こるのは避けられませんし、Mooseもその例外ではありません。後方互換性を保つように最大限の努力は払っていますが、コードベースが互換性を保つためのコードだらけになるのは本末転倒だと思っています。軽々しく変更を加えていこう、というわけではないのですが（正反対です）、私たちは変更をおそれず、エンドユーザにとってなるべく苦痛の少ない状態を保つようベストを尽くしていきます。

後方互換性が失われる変更を加える場合は、規則として「少なくとも」リリース1回分の周知期間をB<設けなければなりません>（大きな変更の場合は周知期間をのばす必要があります）。本当に大きな、あるいは過激な変更を行う場合は、デベロッパーリリースも必要になるかもしれません（これについてはその都度コア開発者が判断します）。

機能を廃止する場合は、よくわかるように何度も警告を出して、ユーザに手元のコードを修正する時間を与えるようにしてください。

後方互換性が失われる変更はすべてL<Moose::Manual::Delta>にB<記載しなければなりません>。このドキュメントにはかならずその修正に対する有用なヒントや対策を載せてください。

=head1 作者

Stevan Little E<lt>stevan@iinteractive.comE<gt>

Chris (perigrin) Prather

Yuval (nothingmuch) Kogman

=head1 COPYRIGHT AND LICENSE

Copyright 2009 by Infinity Interactive, Inc.

L<http://www.iinteractive.com>

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=cut