一般概要 ¶

ブランチの作成と管理 ¶

ブランチベースの開発は、特に複雑なものではありません。トランク（または、作業のソースおよび宛先として最も適したブランチ）からブランチを作成し、そのブランチで作業を行います。Subversion のマージ追跡機能は、この方法で作業する際に必要な精神的なオーバーヘッドを大幅に軽減するのに役立ちました。そのため、この機能を十分に活用すること（Subversion 1.5 以降のクライアントを使用し、すべてのマージをブランチのルートとの間で行うこと）を強く推奨します。

ブランチのログメッセージに関するポリシーについては、「ログメッセージの書き方」のセクションを参照してください。

軽量ブランチ ¶

複数のコミットを伴う段階的な機能やバグ修正に取り組んでおり、中間段階の一部がトランクに適用するには十分に安定していない場合は、/branches に一時ブランチを作成してください。許可を得る必要はありません。自由に行ってください。一時ブランチで実験的なアイデアを試すのも問題ありません。また、上記のすべてのことは、部分的なコミッターだけでなく、完全なコミッターにも当てはまります。他のASFプロジェクトのコミッターにも当てはまりますが、作業しようとしている問題を開発者メーリングリスト（dev@）で相談してください。自己紹介と、取り組む予定の問題を説明してください。

ブランチが完了したら（トランクにマージするか、放棄した場合）、必ず削除することを忘れないでください。

実験的なブランチへのコミットアクセスを提供する際のポリシーについては、「部分的なコミットアクセスに関するセクション」も参照してください。

BRANCH-README ファイル ¶

長期間存続すると予想されるブランチの場合は、ブランチのルートに次の名前のファイルを作成し、定期的に更新することをお勧めします。BRANCH-READMEこのようなファイルは、ブランチの以下の側面を記述するための素晴らしい中心的な場所を提供します。

• ブランチの基本的な目的：修正するためのバグや実装する機能は何か。関連する課題番号は何か。どのようなリストディスカッションスレッドが存在するか。状況を説明するための設計ドキュメントは存在するか。

• 使用しているブランチ管理のスタイル：これは、定期的に親ブランチと同期し、最終的にその親ブランチに再統合される機能ブランチですか？近い将来、親ブランチにマージされる予定のないフォークですか？他のブランチとの関係はありますか？

• ブランチで達成する必要のあるタスクは何ですか？それらのタスクは誰かが担当していますか？さらに設計に関するインプットが必要ですか？他の人はどのようにあなたを助けることができますか？

以下に、私たちが言っていることを示す BRANCH-README ファイルの例を示します。

This branch exists for the resolution of issue #8810, per the ideas
documented in /trunk/notes/frobnobbing-feature.txt.  It is a feature
branch, receiving regular sync merges from /trunk, and expected to be
reintegrated back thereto.

TODO:

  * compose regression tests        [DONE]
  * add frob identification logic   [STARTED (fitz)]
  * add nobbing bits                []

なぜこれほどまでにこだわるのか？それは、このプロジェクトがコミュニケーションとコラボレーションを理想としており、前者が強調される場合に後者が発生する可能性が高いことを理解しているからです。

ブランチをソースにマージするときは、必ずBRANCH-READMEファイルを削除してください。

すべてをドキュメント化する ¶

パブリックか内部かに関わらず、すべての関数は、その関数が何をするかを説明するドキュメントコメントから始める必要があります。ドキュメントには、関数が受け取るすべてのパラメータ、可能なすべての戻り値、および（自明でない場合）関数がエラーを返す可能性のある条件を記述する必要があります。

内部ドキュメントの場合は、ドキュメント文字列でパラメータ名を大文字で記述してください。実際の宣言で大文字でなくても、人間の読者にとって目立つようにするためです。

パブリックまたは準パブリックAPI関数の場合、ドキュメント文字列は宣言されている.hファイルの関数の上に配置する必要があります。それ以外の場合は、.cファイルの関数定義の上に配置します。

構造体型の場合は、構造体自体だけでなく、構造体の個々のメンバーもドキュメント化してください。

実際のソースコードの場合は、各関数のチャンクを内部的にドキュメント化して、Subversionに詳しい人が実装されているアルゴリズムを理解できるようにしてください。明白なドキュメントや過度に冗長なドキュメントを含めないでください。コメントはコードの理解を助けるものであり、妨げるものであってはなりません。

例：

  /*** How not to document.  Don't do this. ***/

  /* Make a foo object. */
  static foo_t *
  make_foo_object(arg1, arg2, apr_pool_t *pool)
  {
     /* Create a subpool. */
     apr_pool_t *subpool = svn_pool_create(pool);

     /* Allocate a foo object from the main pool */
     foo_t *foo = apr_palloc(pool, sizeof(*foo));
     ...
  }

代わりに、次のように適切なサイズのコードチャンクをドキュメント化します。

      /* Transmit the segment (if its within the scope of our concern). */
      SVN_ERR(maybe_crop_and_send_segment(segment, start_rev, end_rev,
                                          receiver, receiver_baton, subpool));

      /* If we've set CURRENT_REV to SVN_INVALID_REVNUM, we're done
         (and didn't ever reach END_REV).  */
      if (! SVN_IS_VALID_REVNUM(current_rev))
        break;

      /* If there's a gap in the history, we need to report as much
         (if the gap is within the scope of our concern). */
      if (segment->range_start - current_rev < 1)
        {
          svn_location_segment_t *gap_segment;
          gap_segment = apr_pcalloc(subpool, sizeof(*gap_segment));
          gap_segment->range_end = segment->range_start - 1;
          gap_segment->range_start = current_rev + 1;
          gap_segment->path = NULL;
          SVN_ERR(maybe_crop_and_send_segment(gap_segment, start_rev, end_rev,
                                              receiver, receiver_baton,
                                              subpool));
        }

Subversionコードを読んで、ドキュメントが実際にはどのように見えるかの概要を把握してください。特に、doxygenの例については、 subversion/include/*.hを参照してください。

パブリックAPIドキュメント ¶

パブリックインターフェースドキュメントには、Doxygen形式を使用します。これは、パブリックヘッダーファイルに含まれるすべてのものを意味します。生成されたドキュメントは、最新および一部の以前のSubversionソース用にWebサイトで公開されています。

ソースをマークアップするために利用可能なdoxygenコマンドのごく一部のみを使用します。doxygenドキュメントを作成する際は、次の規則が適用されます。

• 関数を完全な文章と散文で記述し、パラメータ名の前に@a、型とマクロ名の前に@cを付けてください。
• 複数の単語を表示するには<tt>...</tt>を使用し、タイプライターフォントで1つの単語のみを表示するには@pを使用します。
• TRUE、FALSE、NULLなどの定数値は、すべて大文字にする必要があります。
• 複数の関数が関連している場合は、グループ名を定義し、@defgroupと@{...@}を使用してそれらをグループ化します。

コマンドの完全なリストについては、Doxygenマニュアルを参照してください。

パッチの作成 ¶

最新のソースコードを入手するには、以下を実行します。

svn checkout https://svn.apache.org/repos/asf/subversion/trunk/ svn-trunk

そして、次の指示に従います。INSTALLファイル。（svnクライアントがない場合は、ソースtarballをダウンロードしてください。）

パッチが新しい機能を実装する場合、または大量のコードを変更する場合は、最初に開発者メーリングリスト（dev@）で話し合うことを忘れないでください。（#svn-devのIRCも、メーリングリストでの議論の代わりではなく、議論前の簡単なフィードバックには適切です。IRCで質問する場合は、全員が常にオンラインであるわけではないため（特に週末）、返信があるまでしばらくお待ちください。）これは、コミュニティが提案された機能や実装の詳細に関する懸念を表明し、改善を提案できるようにするためです。フィードバックは後で（コードが記述される前でさえ）提供されるよりも、できるだけ早く提供される方が、すべての関係者にとって常に優れています。

パッチについて質問がある場合は、IRCまたはdev@でお気軽にお尋ねください。

パッチの提出 ¶

パッチをdev@subversion.apache.orgに送信し、件名の先頭を次のようにします。[PATCH]。これにより、パッチマネージャーがパッチをすぐに見つけることができます。たとえば、

   Subject: [PATCH] fix for rev printing bug in svn status

パッチが特定の課題に対応する場合は、課題番号も記載してください。"[PATCH] 課題 #1729: ...". 特定の課題に関心のある開発者は、メールを読む必要があることを知ることができます。

パッチの送信には、1つの論理的な変更を含める必要があります。1つの送信でN個の無関係な変更を混在させないでください。代わりにN個の別々のメールを送信してください。

次のコマンドを使用してパッチを生成します。svn diff -x-pSubversionトランクのワーキングコピーの先頭から。差分を適用するファイルがリビジョン管理下でない場合は、次を使用することで同じ効果が得られます。diff -u.

パッチにログメッセージを含めてください。適切なログメッセージは、潜在的なレビュー担当者がパッチの変更を理解するのに役立ち、適用される可能性が高まります。ログメッセージはメールの本文、またはパッチ添付ファイルの先頭に記述できます（下記参照）。いずれの場合も、「ログメッセージの書き方」に記載されているガイドラインに従い、次のように三重の角括弧で囲む必要があります。

   [[[
   Fix issue #1729: Don't crash because of a missing file.

   * subversion/libsvn_ra_ansible/get_editor.c
     (frobnicate_file): Check that file exists before frobnicating.
   ]]]

（括弧は実際にはログメッセージの一部ではなく、ログメッセージを周囲のコンテキストから明確に区別する方法にすぎません。）

可能であれば、text/x-diff、text/x-patch、またはtext/plainのMIMEタイプでパッチを添付ファイルとして送信してください。ほとんどのメールリーダーはインラインで表示でき、パッチを添付ファイルとして添付することで、メッセージからパッチを簡単に抽出できます。アーカイブまたは圧縮された形式（tar、gzip、zip、bzip2など）でパッチを送信しないでください。これにより、ユーザーがメールリーダーでパッチを直接レビューできなくなります。

これらのMIMEタイプのいずれかでパッチを添付できない場合、またはパッチが非常に短い場合は、メッセージの本文に直接含めてもかまいません。ただし、注意してください。一部のメールエディターは、長い行の途中に不要な改行を挿入して、インラインパッチを改ざんします。メールソフトウェアでこのような処理が行われる可能性があると思われる場合は、代わりに添付ファイルを使用してください。

パッチが新しい機能を実装する場合は、メールでその機能を完全に説明してください。パッチがバグを修正する場合は、バグの詳細を説明し、再現手順を示してください。これらのガイドラインの例外は、パッチが課題データベースの特定の課題に対応する場合です。その場合は、「ログメッセージの書き方」で説明されているように、ログメッセージで課題番号を参照するだけで済みます。

パッチは、適用される前に数回のフィードバックと変更を経ることが通常です。パッチがすぐに承認されなくても、落胆しないでください。それはあなたが失敗したという意味ではなく、すべてのコード送信を注視している多くの人がいることを意味するだけであり、少なくとも少し改善の余地がないパッチはまれです。パッチに対する人々の応答について話し合った後、適切な変更を加えて再送信し、次のラウンドのフィードバックを待って、コミッターが適用するまで、泡立てて、すすぎ、繰り返します。送信する前に、プロジェクトのコーディング規則を確認してパッチに適用することで、いくつかの反復を回避できます。

しばらくの間応答がなく、パッチが適用されているのを確認できない場合は、単に人々が非常に忙しいことを意味する場合があります。遠慮なく再投稿し、まだ応答を待っていることを指摘してください。パッチ管理は高度に並列化可能であり、コーディングだけでなく管理の分担も肩代わりする必要があると考えるとよいでしょう。すべてのパッチは、プロセスを管理してくれる誰かを必要としており、それを行うのに最も適した人は、元の提出者です。