コミュニティへの参加 ¶

SubversionはもともとCollabNet（https://www.collab.net/）が後援し、ホストしていましたが、Apache License, Version 2.0に基づく真のオープンソースプロジェクトです。Subversionの開発者の多くは、Subversionを改善するために雇用主から報酬を受けていますが、その他多くの開発者は、より良いバージョン管理システムの構築に関心のある単なる優れたボランティアです。

コミュニティは主にIRC、メーリングリスト、Subversionリポジトリを通じて存在しています。参加するには、

• irc.libera.chatの#svn-devチャネルに参加してください（WebインターフェースまたはMatrixまたは任意のIRCソフトウェアを使用してください。アーカイブはこちら）。

• 「dev」、「commits」、「announce」のメーリングリストに参加してください。devリストであるdev@subversion.apache.orgでは、ほとんどすべての議論が行われます。すべての開発に関する質問はそこに送信する必要がありますが、最初にリストアーカイブを確認することをお勧めします。「commits」リストは、自動コミットメールを受信します。詳細については、https://subversion.dokyumento.jp/mailing-lists.htmlを参照してください。

• https://svn.apache.org/repos/asf/subversion/trunk/から最新の開発ソースのコピーを入手してください。
  新しい開発は常にtrunkで行われます。バグ修正、機能強化、および新機能は、そこからさまざまなリリースブランチにバックポートされます。

Subversionコミュニティは数年間、年に一度ベルリンでハッカソンを開催しています：2016、2015、2014、2013、2012、2011、および2010 [archive.orgからリンクされています。一部のメディアリンクは機能しません]。

コードを書く、テストする、またはバグデータベースの管理を支援するなど、プロジェクトに参加する方法はたくさんあります。貢献したい場合は、以下を参照してください。

• バグ/問題データベース https://issues.apache.org/jira/projects/SVN/issues

コードを送信するには、パッチをdev@subversion.apache.orgに送信するだけです。いいえ、まずこのファイルの残りの部分を読んでから、パッチをdev@subversion.apache.orgに送信してください。 :-)

問題データベースの管理を支援するには、問題の概要を確認し、無効な問題または他の問題の重複である問題を調べてテストします。両方の種類が非常に一般的です。1つ目は、コードの他の変更の副作用としてバグが意図せずに修正されることがよくあるため、2つ目は、すでに報告されていることに気づかずに問題を提起する人がいるためです。問題が不明な場合は、dev@subversion.apache.orgに質問を投稿してください。（「Subversion：私たちはあなたが私たちを助けるのを助けるためにここにいます！」）

支援するもう1つの方法は、Subversionの自動ビルドとテストスイートの実行をいくつかのプラットフォームで設定し、出力をnotifications@subversion.apache.orgメーリングリストに送信することです。詳細については、メーリングリストページを参照してください。

最後に、Subversionプロジェクトのオンラインの性質と、その事実から生じる人間関係の抽象化にもかかわらず、すべての貢献の終わりには実際の人がいることを認識することが重要です。他のすべてのコミュニティメンバーを、自分が扱われたいように扱ってください。貢献者ではなく、貢献をレビューしてください。他人をイライラさせないでください。また、すぐにイライラしないでください。

理論とドキュメント ¶

1. 設計

   設計仕様は2000年6月に作成され、少し古くなっています。ただし、リポジトリの内部動作とSubversionのさまざまなレイヤーについて、優れた理論的導入を行っています。

2. APIドキュメント

   詳細については、公開APIドキュメントに関するセクションを参照してください。

3. デルタエディター

   Karl Fogelは、O'Reillyの2007年の著書Beautiful Code：Leading Programmers Explain How They Thinkで、Subversionのデルタエディターインターフェースの設計と使用について章を書きました。

4. ネットワークプロトコル

   WebDAVの使用ドキュメントは、SubversionのDAVネットワークプロトコルを紹介するものです。これは、HTTPの拡張版であり、「http://」または「https://」で始まるURLを使用します。

   SVNプロトコルドキュメントには、Subversion ra_svnネットワークプロトコルの正式な説明が含まれています。これは、ポート3690（デフォルト）上のカスタムプロトコルであり、URLは「svn://」または「svn+ssh://」で始まります。

5. ユーザーマニュアル

   Version Control with Subversionは、Subversionを効果的に使用する方法を詳細に示すO'Reillyから出版された書籍です。書籍のテキストは無料で、積極的に改訂されています。オンライン版はhttps://svnbook.red-bean.com/で入手できます。XMLソースと他の言語への翻訳は、https://sourceforge.net/projects/svnbook/の独自のリポジトリで保守されています。

6. システムノート

   システムの特定の側面に関する多くの設計アイデアは、notes/ディレクトリの個々のファイルに文書化されています。

読むべきコード ¶

コードを貢献する前に、既存のコードベースとインターフェースに慣れる必要があります。

Subversionのコピーをチェックアウトします（コミットアクセスのあるアカウントがまだない場合は匿名で）—コードを見ることができるように。

'subversion/include/'内には、巨大なドキュメントコメントを含む多くのヘッダーファイルがあります。これらを読めば、実装の詳細をかなりよく理解できるでしょう。以下に推奨される熟読順序を示します。

1. 基本ビルディングブロック：svn_string.h、svn_error.h、svn_types.h

2. svn_io.h、svn_path.h、svn_hash.h、svn_xml.h

3. 重要なインターフェース：svn_delta.h

4. クライアントサイドのインターフェース：svn_ra.h、svn_wc.h、svn_client.h

5. リポジトリとバージョン管理されたファイルシステム：svn_repos.h、svn_fs.h

Subversion は、C89/C90 の ANSI/ISO C 方言のみを使用し、Apache Portable Runtime (APR) ライブラリを使用することで、移植性を維持しようとしています。APR は Apache httpd サーバーで使用される移植性レイヤーであり、詳細については https://apr.apache.org/ を参照してください。

Subversion は APR に大きく依存しているため、APR の特定のヘッダーファイル (「apr/include/」内を参照) を最初にざっと目を通しておかないと、Subversion を理解するのが難しい場合があります。

• メモリープール：apr_pools.h

• ファイルシステムアクセス：apr_file_io.h

• ハッシュと配列：apr_hash.h、apr_tables.h

Subversion は、信頼性が高く安全なソフトウェアの提供も試みています。これは、C プログラミング言語での安全なプログラミングを理解している開発者によってのみ達成できます。この背景にある完全な理論的根拠については、「notes/assurance.txt」を参照してください。特に、David Wheeler の Secure Programming ( 「notes/assurance.txt」 で言及) を注意深く読むことをお勧めします。変更のセキュリティ上の影響について疑問がある場合は、開発者メーリングリストでレビューを求めることを強くお勧めします。

ディレクトリレイアウト ¶

ソースツリーの大まかなガイド

• doc/
  ユーザーおよび開発者向けドキュメント。

• tools/
  Subversion で動作するが、Subversion が依存していないもの。tools/ 内のコードは、Subversion プロジェクトによって共同で保守されており、Subversion 自体と同じオープンソース著作権の下にあります。

• contrib/
  Subversion で動作するが、Subversion が依存していないもの。Subversion 開発に参加する人もいれば、そうでない人もいる個人によって保守されています。contrib/ 内のコードはオープンソースですが、Subversion 自体とは異なるライセンスまたは著作権所有者を持つ場合があります。

• subversion/
  Subversion 自体のソースコード (外部ライブラリとは対照的)。

• subversion/include/
  Subversion ライブラリのユーザー向けの公開ヘッダーファイル。

• subversion/include/private/
  Subversion ライブラリ内で内部的に共有される非公開ヘッダーファイル。

• subversion/libsvn_fs/
  バージョン管理の「ファイルシステム」API。

• subversion/libsvn_repos/
  `libsvn_fs` コアを中心に構築されたリポジトリ機能。

• subversion/libsvn_delta/
  ツリーデルタ、テキストデルタ、プロパティデルタ用の共通コード。

• subversion/libsvn_wc/
  ワーキングコピー用の共通コード。

• subversion/libsvn_ra/
  リポジトリアクセス用の共通コード。

• subversion/libsvn_client/
  クライアント操作用の共通コード。

• subversion/svn/
  コマンドラインクライアント。

• subversion/tests/
  自動テストスイート。

ブランチングポリシー ¶

Subversion プロジェクトは、アクティブな開発が共通の trunk で行われることを強く推奨します。trunk に加えられた変更は、最も高い可視性を持ち、リリースされていないコードから期待できる最大の演習が行われます。しかし、これがすべての人にとって有益であるためには、私たちの trunk は常に安定していることが期待されます。ビルドできるはずです。動作するはずです。リリース準備ができていないかもしれませんが、テストスイートの準備は確かにできているはずです。

また、大きな変更は、より小さく、論理的なコミットに分割することを強く推奨します。それぞれのコミットは、上記の安定性の要件を満たすことが期待されます。

とは言え、特に大きな変更 (新機能、大規模なコード再編成など) にこれらのポリシーをすべて適用することはほぼ不可能であることを理解しています。そのような状況では、開発タスク専用のカスタムブランチの使用を検討するかもしれません。以下に、ブランチベースの開発作業をスムーズに進めるためのガイドラインをいくつか示します。

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                []

ドキュメント ¶

  /*** 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));
        }

パッチの提出ガイドライン ¶

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

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

   [[[
   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.
   ]]]

コミッター ¶

Subversionプロジェクトのコミッターは、バージョン管理されたリソースへの変更を直接コミットする権利が付与された人々です。プロジェクトは実力主義であり、それは（とりわけ）プロジェクトの運営が作業を行う人々によって処理されることを意味します。コミットアクセスには、フルアクセスと部分アクセスの2種類があります。フルアクセスはツリー内のどこでも、部分アクセスはそのコミッターの特定の専門分野内のみを意味します。すべての貢献はソースに関係なく評価されますが、Subversionにコードを貢献するすべての人がコミットアクセスを獲得するわけではありません。

COMMITTERSファイルには、フルコミッターと部分コミッターの両方がリストされており、各部分コミッターのドメインが示されています。

   Approved by: lundblad

   https://svn.haxx.se/dev/archive-2007-11/0848.shtml
   From: Karl Fogel <kfogel@red-bean.com>
   To: dev@subversion.tigris.org
   Subject: branch liberalization (was: Elego tree conflicts work)
   Date: Tue, 20 Nov 2007 10:49:38 -0800
   Message-Id: <87y7cswy4d.fsf@red-bean.com>

------------------------------------------------------------------------
r32135 | stylesen | 2008-07-16 10:04:25 +0200 (Wed, 16 Jul 2008) | 8 lines

Update "check-license.py" so that it can generate license text applicable
to this year.

Obvious fix.

* tools/dev/check-license.py
  (NEW_LICENSE): s/2005/2008/

------------------------------------------------------------------------

リリース管理者 ¶

Subversionプロジェクトにおけるリリース管理者の役割は、コードを安定させ、パッケージ化し、一般公開するプロセスを処理することです。もし私たちが飛行機を製造していたとしたら、RMは建設チェックリストを見て、機体に航空会社のロゴをペイントし、完成したユニットを顧客に納品する人物でしょう。

そのため、RM（リリース管理者）になること自体に伴う実際の開発作業はありません。あなたが行う必要がある作業はすべて非コーディングです。つまり、人々の調整、情報の集約、および新しい安定版リリースを発表する公的な声としての役割です。RMが行う必要のあるタスクの多くは反復的であり、まだ誰もツールを開発していないため、またはタスクが自動化を少し冗長にする人間による検証を必要とするため、自動化されていません。リリースプロセスについては、Subversion リリースの作成のセクションで詳しく読むことができます。

この段階で、RMの役割は地味だと感じるかもしれませんが、それはある意味で正しいです。プロジェクト内で名声と富をもたらすようなポジションを探しているなら、trunkで本当に必要なものを実装する方が良いでしょう。リリースを気にせずコードに集中したい人々を本当に助けたいと考えているなら、RMはあなたに向いているでしょう。

リリース管理の知識をより広く普及させるために、RMの役割は現在、さまざまな犠牲者ボランティアの間で持ち回り制になっています。

パッチマネージャー ¶

Subversionには通常、パッチマネージャーがおり、その仕事はdev@メーリングリストを監視し、パッチが「見落とされない」ようにすることです。

これは、「[PATCH]」というメールを含むすべてのスレッドを監視し、スレッドの進捗状況に基づいて適切なアクションを実行することを意味します。スレッドが自然に解決した場合（パッチがコミットされた場合、またはパッチを適用する必要がないという合意が得られた場合など）、それ以上の措置は必要ありません。しかし、明確な決定なしにスレッドが消滅した場合、パッチは課題追跡システムに保存する必要があります。これは、そのパッチに関する議論スレッドの要約と、関連するメーリングリストアーカイブへのリンクが、追跡システムのいくつかの課題に追加されることを意味します。既存の課題追跡項目のパッチの場合、パッチはその項目に保存されます。それ以外の場合は、適切なタイプ（「DEFECT」、「FEATURE」、または「ENHANCEMENT」（「PATCH」ではない））の新しい課題が作成され、パッチがその新しい課題に保存され、「パッチ」キーワードが課題に記録されます。

パッチマネージャーには、Subversionの基本的な技術的理解と、スレッドをざっと読んで合意に達したかどうか、そしてそうである場合はどのような合意かを大まかに理解する能力が必要です。Subversionの開発経験やコミットアクセスは必要ありません。メール閲覧ソフトウェアの使用に関する専門知識はオプションですが、推奨されます :-)。

現在のパッチマネージャーは、Gavin 'Beau' Baumanis <gavin@thespidernet.com> です。

コードのモジュール性とインターフェースの可視性 ¶

Subversionのコードとヘッダーファイルは、いくつかの重要な線に沿って分離されています。ライブラリ固有のものとライブラリ間のもの、パブリックとプライベートです。この分離は、主に適切なモジュール性とコード編成に重点を置いているためですが、広く採用されているパブリックAPIの提供者および保守者としての約束のためでもあります。Subversionで新しい関数を作成する際には、これらの点を慎重に検討し、進めながら自問自答する必要があります。

「新しいコードの利用者は、単一のライブラリ内の特定のソースコードファイルにローカルですか？」 そうである場合、おそらく同じソースファイル内の静的関数を使用することになります。

「新しい関数は、このライブラリ内の他のソースコードは使用する必要があるが、ライブラリ*外部*からは何も使用する必要がないようなタイプですか？」 その場合は、非静的な、二重アンダースコア付きの名前の関数（例：svn_foo__do_something）を使い、そのプロトタイプを適切なライブラリ固有のヘッダーファイルに記述することになります。

「異なるライブラリからコードにアクセスする必要がありますか？」 ここでは、さらにいくつかの質問に答える必要があります。たとえば、「コードは、元々配置しようとしていたライブラリに配置する必要がありますか、それともlibsvn_subrなどのより一般的なユーティリティライブラリに配置する必要がありますか？」 いずれにしても、ライブラリ間のヘッダーファイルを使用することになります。ただし、どちらにするかを決定する前に、次の質問をご覧ください...

「コードは、永続的に維持できる合理的なAPIを持ち、SubversionのパブリックAPIの提供に価値をもたらすものですか？」 そうである場合は、パブリックAPI内のプロトタイプを、すぐにsubversion/include/に追加することになります。そうでない場合は、計画を再確認してください。機能の抽象化に最適な方法を選択していない可能性があります。しかし、Subversion自体以外のソフトウェアには明らかに役に立たない関数をライブラリ間で共有する必要がある場合もあります。そのような場合は、subversion/include/private/.

コーディングスタイル ¶

SubversionはANSI Cを使用しており、GNUコーディング標準に従っています。ただし、関数の名前とパラメーターリストの開き括弧の間にスペースは入れません。Emacsユーザーは、svn-dev.elをロードするだけで適切なインデント動作を得ることができます（ここにあるほとんどのソースファイルは、`enable-local-eval`が適切に設定されている場合、自動的にロードします）。

GNUコーディング標準の詳細については、https://www.gnu.org/prep/standards.htmlをご覧ください。以下は、最も重要な書式設定のガイドラインを示す簡単な例です。パラメーターリストの開き括弧の前にスペースを入れないという例外を含みます。

   char *                                     /* func type on own line */
   argblarg(char *arg1, int arg2)             /* func name on own line */
   {                                          /* first brace on own line */
     if ((some_very_long_condition && arg2)   /* indent 2 cols */
         || remaining_condition)              /* new line before operator */
       {                                      /* brace on own line, indent 2 */
         arg1 = some_func(arg1, arg2);        /* NO SPACE BEFORE PAREN */
       }                                      /* close brace on own line */
     else
       {
         do                                   /* format do-while like this */
           {
             arg1 = another_func(arg1);
           }
         while (*arg1);
       }
   }

一般的に、演算子の優先順位を確信している場合でも括弧を多用し、「コードの詰め込み」を避けるためにスペースと改行を惜しまないでください。垂直方向の密度をあまり気にしないでください。画面に追加の行を収めるよりも、コードを読みやすくする方が重要です。

改ページの使用 ¶

コードとプレーンテキストの散文ファイルの両方で、セクションの区切りには改ページ（Ctrl-L文字、ASCII 12）を使用しています。各セクションは改ページで始まり、改ページの直後にセクションのタイトルが続きます。

これは、`pages-directory`や`narrow-to-page`などのEmacsページコマンドを使用するユーザーを支援します。このような人々はあなたが思うほど少なくなく、もしあなたがその一人になりたいのであれば、.emacsに（require 'page-ext）を追加して、時々C-x C-p C-hと入力してください。

エラーメッセージの規約 ¶

エラーメッセージには、以下の規約が適用されます。

• subversion/include/svn_error_codes.hにある一般的なエラーメッセージに追加する情報がある場合にのみ、特定のエラーメッセージを提供してください。

• メッセージは大文字で始まります。

• メッセージを70文字未満に保つようにしてください。

• エラーメッセージをピリオド（「.」）で終わらせないでください。

• エラーメッセージに改行文字を含めないでください。

• 情報の引用は、単一引用符を使用します（例："'some info'"）。

• エラーが発生した関数の名前をエラーメッセージに含めないでください。Subversionが「--enable-maintainer-mode」configureフラグを使用してコンパイルされている場合、この情報自体が提供されます。

• エラー文字列にパスまたはファイル名を含める場合は、必ずそれらを引用符で囲んでください（例：「'/path/to/repos/userfile'が見つかりません」）。

• エラー文字列にパスまたはファイル名を含める場合は、含める前に必ずsvn_dirent_local_style()を使用して変換してください（Subversion APIとの間で受け渡されるパスは、正規形であると想定されているため）。

• Subversion固有の省略形を使用しないでください（例：「repo」の代わりに「repository」、「wc」の代わりに「working copy」を使用してください）。

• エラーに説明を追加する場合は、次のようにコロンと説明を続けて報告してください。

         "Invalid " SVN_PROP_EXTERNALS " property on '%s': "
         "target involves '.' or '..'".
       

• 提案やその他の追加は、次のようにセミコロンの後に追加できます。

         "Can't write to '%s': object of same name already exists; remove "
         "before retrying".
       

• これらの規約の範囲内に留まるようにしてください。そのため、「--」などの他の区切り文字でエラーメッセージの異なる部分を区切らないようにしてください。

また、ローカライゼーションについても読んでください。

APRプールの使用規約 ¶

（これは、APRプールの仕組みを基本的に理解していることを前提としています。詳細については、apr_pools.hをご覧ください。）

Subversionライブラリを使用するアプリケーションは、Subversion関数を呼び出す前にapr_initialize()を呼び出す必要があります。

Subversionの一般的なプール使用戦略は、次の2つの原則に要約できます。

1. プールを作成した呼び出しレベルは、そのプールをクリアまたは破棄する唯一の場所です。

2. 境界のない回数を反復処理する場合は、反復処理に入る前にサブプールを作成し、ループ内で使用し、各反復処理の開始時にクリアし、ループが完了したら破棄します。例：

            apr_pool_t *iterpool = svn_pool_create(scratch_pool);
   
            for (i = 0; i < n; ++i)
            {
              svn_pool_clear(iterpool);
              do_operation(..., iterpool);
            }
   
            svn_pool_destroy(iterpool);
          

上記ルールをサポートするために、さまざまなプールの有効期間を表す規約として、次のプール名を使用します。

• result_pool：関数の出力が割り当てられるプール。結果プールの宣言は、関数の引数リストに常に記述する必要があり、ローカルブロック内には決して記述しないでください。（ただし、すべての関数に結果プールが必要なわけではありません。）

• scratch_pool：関数ローカルのすべてのデータが割り当てられるプール。このプールも呼び出し元によって提供され、呼び出し元は制御が戻った直後にこのプールをクリアすることを選択できます。

• iterpool：上記の例に従って、ループ内で使用される反復プール。

（注：一部のレガシーコードでは、単一のpool関数引数を使用しており、これは結果プールとスクラッチプールの両方として機能します。）

ループで境界付けられたデータにiterpoolを使用することにより、関数が（エラーなどが原因で）ループ内から突然戻った場合に、O(N)ではなくO(1)のメモリリークを確実にします。そのため、関数全体で永続化するデータにはサブプールを作成しないでください。代わりに、呼び出し元から渡されたプールを使用してください。そのメモリは、呼び出し元のプールがクリアまたは破棄されたときに再利用されます。呼び出し元がループ内で呼び出し先を呼び出している場合は、各反復処理でプールをクリアするのは呼び出し元の責任であると信じてください。同じロジックが呼び出しスタック全体に伝播されます。

使用するプールは、コードの読者がオブジェクトの有効期間を理解するのに役立ちます。特定のオブジェクトはループの1回の反復でのみ使用されますか、それともループの終わりを超えて存続する必要がありますか？たとえば、プールの選択は、このコードで何が起こっているかについて多くのことを示しています。

      apr_hash_t *persistent_objects = apr_hash_make(result_pool);
      apr_pool_t *iterpool = svn_pool_create(scratch_pool);

      for (i = 0; i < n; ++i)
      {
        const char *intermediate_result;
        const char *key, *val;
        
        svn_pool_clear(iterpool);
        SVN_ERR(do_something(&intermediate_result, ..., iterpool));
        SVN_ERR(get_result(intermediate_result, &key, &val, ...,
                           result_pool));
        apr_hash_set(persistent_objects, key, APR_HASH_KEY_STRING, val);
      }

      svn_pool_destroy(iterpool);
      return persistent_objects;

これらの原則が十分に理解される前に書かれた一部のレガシーコードを除いて、Subversionでのほぼすべてのプールの使用は上記のガイドラインに従っています。

そのようなレガシーなパターンの一つに、オブジェクトをプール内に割り当て、そのプールをオブジェクトに格納し、そのプールを（直接または `close_foo()` 関数を介して）解放してオブジェクトを破棄するというものがあります。

例えば

   /*** Example of how NOT to use pools.  Don't be like this. ***/

   static foo_t *
   make_foo_object(arg1, arg2, apr_pool_t *pool)
   {
      apr_pool_t *subpool = svn_pool_create(pool);
      foo_t *foo = apr_palloc(subpool, sizeof(*foo));

      foo->field1 = arg1;
      foo->field2 = arg2;
      foo->pool   = subpool;
   }

   [...]

   [Now some function calls make_foo_object() and returns, passing
   back a new foo object.]

   [...]

   [Now someone, at some random call level, decides that the foo's
   lifetime is over, and calls svn_pool_destroy(foo->pool).]

これは魅力的ですが、プールの使用目的を損なっています。プールの目的は個々の割り当てをそれほど気にせず、むしろ全体的なパフォーマンスとライフタイムグループを重視することです。代わりに、`foo_t` は一般的に `pool` フィールドを持つべきではありません。現在のプールに必要な数の foo オブジェクトを割り当てるだけでよいのです。そのプールがクリアまたは破棄されると、それらはすべて同時に消滅します。

プールの破棄時に、プールに関連付けられたリソースがどのようにクリーンアップされるかの詳細については、例外処理のセクションも参照してください。

要約すると

• オブジェクトは独自のプールを持つべきではありません。オブジェクトは、コンストラクタの呼び出し元によって定義されたプールに割り当てられます。呼び出し元はオブジェクトのライフタイムを知っており、プールを介して管理します。

• 関数は、その操作のためにプールを作成/破棄すべきではありません。呼び出し元から提供されたプールを使用する必要があります。繰り返しますが、呼び出し元は関数がどのように使用されるか、どのくらいの頻度で使用されるか、何回使用されるかなどについてより多くを知っています。したがって、関数のメモリ使用量を管理する必要があります。

  たとえば、タイトなループ内で複数回呼び出される関数について考えてみてください。呼び出し元は各反復でスクラッチプールをクリアします。したがって、内部サブプールの作成は不要であり、かなりのオーバーヘッドになる可能性があります。代わりに、関数は渡されたプールを使用する必要があります。

• 上限のない反復が発生する場合は常に、反復サブプールを使用する必要があります。

• 上記のすべてを考慮すると、すべての関数にプールを渡すことがほぼ必須となります。オブジェクトはプールを自分自身のために記録せず、呼び出し元は常にメモリを管理することになっているため、各関数は、何らかの隠れた魔法のプールに頼るのではなく、プールを必要とします。限定的なケースでは、オブジェクトはサブパーツを構築できるように、構築に使用されたプールを記録できますが、これらのケースは慎重に検討する必要があります。

プールの使用に関する問題を診断するためのヒントについては、メモリリークの追跡も参照してください。

APRステータスコード ¶

APRステータスコード (APR_SUCCESS を除く) は、直接比較ではなく、常に APR_STATUS_IS_...() マクロで確認してください。これは、非 Unix プラットフォームへの移植性のために必要です。

例外処理 ¶

さて、Subversion での例外の使い方は次のとおりです。

1. 例外は `svn_error_t` 構造体に格納されます。

   typedef struct svn_error_t
   {
     apr_status_t apr_err;      /* APR error value, possibly SVN_ custom err */
     const char *message;       /* details from producer of error */
     struct svn_error_t *child; /* ptr to the error we "wrap" */
     apr_pool_t *pool;          /* place to generate message strings from */
     const char *file;          /* Only used iff SVN_DEBUG */
     long line;                 /* Only used iff SVN_DEBUG */
   } svn_error_t;
   

2. エラーの *最初の* 作成者である場合は、次のようにします。

   return svn_error_create(SVN_ERR_FOO, NULL, 
                           "User not permitted to write file");
       

   NULL フィールドに注目してください...これは、このエラーに子がないこと、つまり最下位のエラーであることを示します。

   エラーメッセージの書き方に関するセクションも参照してください。

   Subversion は、内部的に UTF-8 を使用してデータを保存します。これは「メッセージ」文字列にも適用されます。APR は、現在のロケールでデータを返すことを想定しているため、APR が返すテキストは、メッセージ文字列に含める前に UTF-8 に変換する必要があります。

3. エラーを *受信* した場合は、3 つの選択肢があります。

   1. 自分でエラーを処理します。独自のコードを使用するか、プリミティブな `svn_handle_error(err)` を呼び出すだけです。（このルーチンは、エラーのスタックを巻き戻し、UTF-8 から現在のロケールに変換してメッセージを出力します。）

      ルーチンが無視または自分で処理しようとするエラーを受け取った場合は、必ず `svn_error_clear()` を使用してクリーンアップしてください。このようなエラーがクリアされない場合は、*メモリリーク* を構成します。

      エラーを返す関数は、出力パラメータを初期化する必要はありません。

   2. エラーをそのまま上位にスローします。

              error = some_routine(foo);
              if (error)
                return svn_error_trace(error);
              

      実際には、これを行うより良い方法は、同じことを行う `SVN_ERR()` マクロを使用することです。

              SVN_ERR(some_routine(foo));
              

   3. エラーを上位にスローし、新しいエラー構造体に "子" 引数として含めることでラップします。

              error = some_routine(foo);
              if (error)
                {
                 svn_error_t *wrapper = svn_error_create(SVN_ERR_FOO, error,
                                                         "Authorization failed");
                 return wrapper;
                }
              

      もちろん、子と同じフィールドを持ち、カスタムメッセージを除くラッパーエラーを作成するための便利なルーチンがあります。

              error = some_routine(foo);
              if (error)
                {
                 return svn_error_quick_wrap(error, 
                                             "Authorization failed");
                }
              

      同様のことは、`SVN_ERR_W()` マクロを使用することによって行うことも（そして行うべきです）できます。

                SVN_ERR_W(some_routine(foo), "Authorization failed");
              

   (b) と (c) のケースでは、ルーチンによって割り当てられ、プールに関連付けられているリソースは、プールの破棄時に自動的にクリーンアップされることを知っておくことが重要です。これは、エラーを渡す前にこれらのリソースをクリーンアップする必要がないことを意味します。したがって、`SVN_ERR()` および `SVN_ERR_W()` マクロを使用しない理由はありません。プールに関連付けられたリソースは次のとおりです。

   • メモリ

   • ファイル

     `apr_file_open` で開かれたすべてのファイルは、プールのクリーンアップ時に閉じられます。Subversion は、その `svn_io_file_*` API でこの関数を使用します。つまり、`svn_io_file_*` または `apr_file_open` で開かれたファイルは、プールのクリーンアップ時に閉じられます。

     一部のファイル（たとえば、ロックファイル）は、操作が完了したときに削除する必要があります。APR には、この目的のための `APR_DELONCLOSE` フラグがあります。次の関数は、プールのクリーンアップ時に削除されるファイルを作成します。

     • `apr_file_open` および `svn_io_file_open`（`APR_DELONCLOSE` フラグが渡された場合）

     • `svn_io_open_unique_file`（`delete_on_close` で TRUE が渡された場合）

     ロックされたファイルは、`svn_io_file_lock` を使用してロックされていた場合、ロック解除されます。

4. `SVN_ERR()` マクロは、`SVN_ERR__TRACING` が定義されている場合に、ラップされたエラーを作成します。これは、開発者がエラーの原因を特定するのに役立ち、`configure` の `--enable-maintainer-mode` オプションで有効にできます。

5. 場合によっては、呼び出された関数が返すものをそのまま返したい場合があります。通常、自分の関数の最後に返します。結果を直接返すという誘惑を避けてください。

       /* Don't do this! */
       return some_routine(foo);

   代わりに、`svn_error_trace` メタ関数を使用して値を返します。これにより、有効になっているときにスタックトレースが正しく行われることが保証されます。

       return svn_error_trace(some_routine(foo));

安全なコーディングのガイドライン ¶

他のほとんどすべてのプログラミング言語と同様に、C には、攻撃者が予測可能な方法でプログラムを失敗させることができ、多くの場合、攻撃者の利益になる望ましくない機能があります。これらのガイドラインの目的は、Subversion プロジェクトに適用される C の落とし穴を認識させることです。最も熟練した偏執的なプログラマーでも時折間違いを犯すため、同僚のコードをレビューする際には、これらの落とし穴を念頭に置くことをお勧めします。

入力検証とは、合法的な入力を定義し、それ以外のすべてを拒否する行為です。コードは、信頼できないすべての入力に対して入力検証を実行する必要があります。

セキュリティ境界

Subversion サーバーコードのセキュリティ境界は、監査人が境界の品質をすばやく判断できるように、そのように識別する必要があります。セキュリティ境界は、実行中のコードがユーザーが持っていない情報にアクセスできる場合、またはコードが要求を行うユーザーの特権よりも高い特権で実行される場合に存在します。そのような典型的な例は、アクセス制御を実行するコードまたは SUID ビットが設定されたアプリケーションです。

セキュリティ境界への呼び出しを行う関数には、渡された引数の検証チェックを含める必要があります。それ自体がセキュリティ境界である関数は、受信した入力を監査し、不適切な値で呼び出されたときにアラームを出す必要があります。

[### todo: ここに Subversion からのいくつかの例が必要です...]

文字列操作

文字列に書き込む標準 C ライブラリ関数ではなく、`apr_strings.h` で提供されている文字列関数を使用してください。APR 関数は、境界チェックと宛先割り当てを自動的に行うため、より安全です。プレーンな C 文字列関数を使用することが理論的に安全な状況（たとえば、ソースと宛先の長さをすでに知っている場合）があるかもしれませんが、コードが脆弱でなくなり、レビューしやすくなるため、とにかく APR 関数を使用してください。

パスワードの保存

ユーザーがパスワードを秘密に保つのを支援します。クライアントがローカルでパスワードを読み書きする場合、ファイルがモード 0600 であることを確認する必要があります。ファイルが他のユーザーによって読み取り可能な場合、クライアントは、暴露の危険があるため、ファイルモードを変更するようにユーザーに指示するメッセージで終了する必要があります。

スタックされたリソースの破棄 ¶

アプリケーションの正常な機能を確保するために、一部のリソースは破棄する必要があります。このようなリソースには、特に Windows では開いているファイルを削除できないため、ファイルが含まれます。

ストリームを作成して返す API を作成する場合、バックグラウンドでこのストリームはファイルまたは他のストリームにスタックされる可能性があります。リソースの正しい破棄を確実にするために、ストリームが構築されている場合、構築されている（所有している）ストリームのデストラクタを正しく呼び出す必要があります。

最初に https://svn.haxx.se/dev/archive-2005-12/0487.shtml で、その後 https://svn.haxx.se/dev/archive-2005-12/0633.shtml で、これはファイル、ストリーム、エディター、ウィンドウハンドラーに関してより一般的な用語で議論されました。

グレッグ・ハドソンが言ったように

検討した結果、ここで私たちがあるべき場所を次に示します。

• 基になるオブジェクトから読み取りまたは書き込みを行うストリームは、そのオブジェクトを所有します。つまり、ストリームを閉じると、該当する場合、基になるオブジェクトが閉じます。
• ストリームを作成したレイヤー（関数またはデータ型）は、上記規則が適用される場合を除き、ストリームを閉じる責任があります。
• ウィンドウハンドラーは、奇妙な種類のストリームと見なされ、最後の NULL ウィンドウを渡すことは、ストリームを閉じると見なされます。

apply_textdelta をウィンドウハンドラーの作成と考えると、それほど遠くはないと思います。`svn_stream_from_aprfile` は、その補助ファイル所有しておらず、`svn_txdelta_apply` は、渡されたウィンドウストリームを閉じる責任を誤って負っており、他にもいくつかの逸脱がある可能性があります。

ただし、上記の規則には 1 つの例外があります。ストリームが関数に引数として渡された場合（たとえば、`svn_client_cat2()` の 'out' パラメータ）、そのルーチンはそのリソースを作成しなかったため、ストリームのデストラクタを呼び出すことはできません。

`svn_client_cat2()` がストリームを作成する場合、そのストリームのデストラクタも呼び出す必要があります。上記のモデルでは、そのストリームは 'out' パラメータのデストラクタを呼び出します。しかし、'out' パラメータを破棄する責任は他にあります。これは間違っています。

この問題を解決するために、少なくともストリームの場合には、svn_stream_disown() が導入されました。この関数はストリームをラップし、その上に積み重ねられたストリームが破棄しようとした場合でも、そのストリームが破棄されないようにします。

可変長引数リスト ¶

可変個の引数を受け取り、リストがヌルポインタ定数で終端されることを期待する関数を呼び出す場合（そのような関数の例はapr_pstrcat）、リストを終端するためにNULLシンボルを使用しないでください。コンパイラとプラットフォームによっては、NULLがポインタサイズの定数である場合とそうでない場合があります。そうでない場合、関数は引数リストの末尾を超えてデータを読み取ってしまう可能性があります。

代わりに、SVN_VA_NULL(1.9以降でsvn_types.hで定義) を使用してください。これはヌルポインタ定数であることが保証されています。例を以下に示します。

   return apr_pstrcat(cmd->temp_pool, "Cannot parse expression '",
                      arg2, "' in SVNPath: ", expr_err, SVN_VA_NULL);

その他のコーディング規約 ¶

GNU標準に加えて、Subversionでは以下の規約を使用しています。

• ほとんどのSubversion APIへの入力としてパスまたはファイル名を使用する場合は、svn_dirent_internal_style() APIを使用して、Subversionの内部/正規形式に変換してください。または、Subversion APIからパスまたはファイル名を出力として受け取る場合は、svn_dirent_local_style() APIを使用して、プラットフォームで期待される形式に変換してください。

• コードのインデントには、タブは決して使用せず、スペースのみを使用してください。タブの表示幅は標準化されておらず、いずれにしてもスペースを使用するインデントを手動で調整する方が簡単です。

• 行を79桁に制限して、最小限の標準ディスプレイウィンドウでコードが適切に表示されるようにします。（インデント、引用符などによって数桁余分な桁が占められている80桁のテキストブロックを宣言する場合など、各行を2つに分割すると不必要に面倒になる場合は例外があります。）

• 公開されているすべての関数、変数、および構造体には、libsvn_wcのsvn_wc_adm_openのように、対応するライブラリ名で示さなければなりません。ライブラリプライベートヘッダーファイル（libsvn_wc/wc.hなど）で作成されたライブラリ内部のすべての宣言は、ライブラリのプレフィックスの後に2つのアンダースコア（svn_wc__ensure_directoryなど）で示す必要があります。1つのファイル（libsvn_wc/update_editor.c内の静的関数get_entry_urlなど）にプライベートなすべての宣言は、追加の名前空間装飾を必要としません。ライブラリの外部で使用する必要があるが、公開されていないシンボルは、include/private/ディレクトリにある共有ヘッダーファイルに入れられ、二重アンダースコア表記を使用します。このようなシンボルは、Subversionコアコードでのみ使用できます。

  まとめると

           /* Part of published API: subversion/include/svn_wc.h */
           svn_wc_adm_open()            
           #define SVN_WC_ADM_DIR_NAME ...
           typedef enum svn_wc_schedule_t ...
  
           /* For use within one library only: subversion/libsvn_wc/wc.h */
           svn_wc__ensure_directory()   
           #define SVN_WC__BASE_EXT ... 
           typedef struct svn_wc__compat_notify_baton_t ...
  
           /* For use within one file: subversion/libsvn_wc/update_editor.c */ 
           get_entry_url()
           struct handler_baton {
  
           /* For internal use in svn core code only:
              subversion/include/private/svn_wc_private.h */
           svn_wc__entry_versioned()
        

  Subversion 1.5より前は、ライブラリの外部で使用する必要があったプライベートシンボルは、二重アンダースコア表記を使用して、パブリックヘッダーファイルに入れられていました。この方法は廃止され、そのようなシンボルはすべて、後方互換性のために維持されているレガシーです。

• ユーザーに印刷（または他の方法で利用可能）にされる可能性のあるテキスト文字列では、パスやその他の引用可能なものについては、常にフォワード引用符のみを使用してください。たとえば

           $ svn revert foo
           svn: warning: svn_wc_is_wc_root: 'foo' is not a versioned resource
           $
        

  以前は、最初の引用符にバックティック（`foo' の代わりに 'foo'）を使用する文字列がたくさんありましたが、一部のフォントでは見栄えが悪く、一部の人の自動強調表示も混乱させたため、常にフォワード引用符を使用するという規約に落ち着きました。

• Emacsを使用する場合は、必要に応じてsvn-dev.elとsvnbook.elを取得できるように、.emacsファイルに次のようなものを入れてください。

           ;;; Begin Subversion development section
           (defun my-find-file-hook ()
             (let ((svn-tree-path (expand-file-name "~/projects/subversion"))
                   (book-tree-path (expand-file-name "~/projects/svnbook")))
               (cond
                ((string-match svn-tree-path buffer-file-name)
                 (load (concat svn-tree-path "/tools/dev/svn-dev")))
                ((string-match book-tree-path buffer-file-name)
                 ;; Handle load exception for svnbook.el, because it tries to
                 ;; load psgml, and not everyone has that available.
                 (condition-case nil
                     (load (concat book-tree-path "/src/tools/svnbook"))
                   (error
                    (message "(Ignored problem loading svnbook.el.)")))))))
  
           (add-hook 'find-file-hooks 'my-find-file-hook)
           ;;; End Subversion development section
        

  もちろん、セットアップに合わせてパスをカスタマイズする必要があります。正規表現をより選択的に文字列照合することもできます。たとえば、ある開発者は次のように述べています。

        > Here's the regexp I'm using:
        > 
        >     "src/svn/[^/]*/\\(subversion\\|tools\\|build\\)/"
        >
        > Two things to notice there: (1) I sometimes have several
        > working copies checked out under ...src/svn, and I want the
        > regexp to match all of them; (2) I want the hook to catch only
        > in "our" directories within the working copy, so I match
        > "subversion", "tools" and "build" explicitly; I don't want to
        > use GNU style in the APR that's checked out into my repo. :-)
        

• 私たちは、個々の著者の名前でファイルをマークしないという伝統を持っています（つまり、ソースファイルの先頭に「著者：foo」や「@author foo」のような行を特別な位置に置きません）。これは、縄張り意識を助長しないためです。たとえファイルに1人の著者しかいない場合でも、他の人が自由に編集できるようにしたいと考えています。誰かがファイルに対する個人的な主張を立てているように見えると、人々は不必要に躊躇する可能性があります。

• 文末と次の文の先頭の間には、2つのスペースを入れます。これは読みやすさを向上させ、エディターの文の移動と操作のコマンドを使用できるようにします。

• コード全体で維持されている、言葉にされていない他の多くの規約があります。それらは誰かが意図せずにそれらに従わなかった場合にのみ気付かれます。物事が行われる方法を注意深く観察し、疑問がある場合は質問してください。

ログメッセージの書き方 ¶

すべてのコミットにはログメッセージが必要です。

ログメッセージの対象読者は、Subversionにはすでに精通しているが、この特定のコミットには必ずしも精通していない開発者です。通常、誰かが変更を振り返って読むとき、その変更に関するすべてのコンテキストを頭の中に持っているわけではありません。これは、変更の作成者であっても当てはまります！すべての議論やメーリングリストのスレッドなどは忘れられている可能性があり、変更の内容の手がかりはログメッセージとdiff自体からのみ得られます。人々は驚くほど頻繁に変更を再検討します。たとえば、元のコミットから数か月後、変更がメンテナンスブランチに移植される場合があります。

ログメッセージは変更の導入部です。

• ブランチで作業している場合は、ログメッセージの先頭に

     On the 'name-of-branch' branch: (Start of your log message)
  

• ログメッセージは、変更の一般的な性質を示す1行で開始し、必要に応じて説明段落を続けます。

これは、開発者がログメッセージの残りの部分を読むための適切な心構えになるのに役立つだけでなく、各コミットの最初の行をIRCのようなリアルタイムフォーラムにエコーする「ASFBot」ボットにも役立ちます。（詳細については、https://wilderness.apache.org/を参照してください）

コミットが1つのファイルに対する1つの簡単な変更である場合は、一般的な説明を省略して、以下に示す標準のファイル名-シンボル形式で詳細な説明に直接進むことができます。

ログメッセージ全体を通して、文節ではなく、完全な文を使用してください。文節はあいまいであることが多く、意味を書き出すのに数秒しかかかりません。「Doc fix」、「New file」、「New function」などの特定の文節は、標準的な慣用句であり、それ以上の詳細はソースコードに記述する必要があるため、許容されます。

ログメッセージには、このコミットで削除されるシンボル名を含む、影響を受けるすべての関数、変数、マクロ、makefileターゲット、文法規則などを名前を付けてください。これは、後でログを検索するのに役立ちます。ワイルドカードで名前を隠さないでください。グロブされた部分は、後で誰かが検索する可能性があるためです。たとえば、これは良くありません。

   * subversion/libsvn_ra_pigeons/twirl.c
     (twirling_baton_*): Removed these obsolete structures.
     (handle_parser_warning): Pass data directly to callees, instead
      of storing in twirling_baton_*.

   * subversion/libsvn_ra_pigeons/twirl.h: Fix indentation.

後で誰かが「twirling_baton_fast」に何が起こったのかを理解しようとしたときに、「_fast」を検索するだけでは見つからない可能性があります。より良いエントリは次のようになります。

   * subversion/libsvn_ra_pigeons/twirl.c
     (twirling_baton_fast, twirling_baton_slow): Removed these
      obsolete structures. 
     (handle_parser_warning): Pass data directly to callees, instead
      of storing in twirling_baton_*. 

   * subversion/libsvn_ra_pigeons/twirl.h: Fix indentation.

ワイルドカードは、「handle_parser_warning」の説明では問題ありません。ただし、2つの構造体がログエントリの他の場所でフルネームで言及されている場合に限ります。

ログメッセージにプロパティの変更も含める必要があります。たとえば、トランクの「svn:ignore」プロパティを変更した場合は、ログに次のようなものを入力する可能性があります。

   * trunk/ (svn:ignore): Ignore 'build'.

上記は、サブバージョンによって保守される「svn:mergeinfo」のようなものではなく、あなたが保守するプロパティにのみ適用されます。

各ファイルは「*」で始まる独自のエントリを取得し、ファイル内の変更はシンボルごとにグループ化され、シンボルは括弧で囲まれ、コロンが続き、変更を説明するテキストが続きます。変更されたファイルが1つだけの場合でも、この形式に従ってください。一貫性は読みやすさを助けるだけでなく、ソフトウェアがログエントリを自動的に色分けすることもできます。

上記に対する例外として、複数のファイルでまったく同じ変更を加えた場合は、変更されたすべてのファイルを1つのエントリにリストします。たとえば

   * subversion/libsvn_ra_pigeons/twirl.c,
     subversion/libsvn_ra_pigeons/roost.c:
     Include svn_private_config.h.

変更されたすべてのファイルがソースツリーの奥深くに存在する場合は、変更エントリの前に共通のプレフィックスを書き留めることで、ファイル名エントリを短縮できます。

   [in subversion/bindings/swig/birdsong]

   * dialects/nightingale.c (get_base_pitch): Allow 3/4-tone
     pitch variation to account for trait variability amongst
     isolated populations Erithacus megarhynchos.

   * dialects/gallus_domesticus.c: Remove. Unreliable due to
     extremely low brain-to-body mass ratio.

変更がイシュートラッカーの特定の問題に関連している場合は、ログメッセージに「issue #N」のような文字列を含めますが、変更の内容を必ず要約してください。たとえば、パッチがissue #1729を解決する場合、ログメッセージは次のようになる可能性があります。

   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.

関連する変更をまとめてください。たとえば、svn_ra_get_ansible()を非推奨にして、svn_ra_get_ansible2()を作成する場合、これらの2つのものはログメッセージで互いに近くにある必要があります。

   * subversion/include/svn_ra.h
     (svn_ra_get_ansible2): New prototype, obsoletes svn_ra_get_ansible.
     (svn_ra_get_ansible): Deprecate.

大規模な変更または変更グループの場合は、ログエントリを空白行で区切られた段落にグループ化します。各段落は、1つの目標を達成する一連の変更である必要があり、各グループは変更を要約する1つまたは2つの文で開始する必要があります。本当に独立した変更は、もちろん個別のコミットで行う必要があります。

誰かがパッチをコミットしている場合、または提案された変更をコミットしている場合に、他の人にクレジットを付与する方法については、「クレジット」を参照してください。

現在のコードを理解するためにログエントリが必要になることは決してありません。ログに重要な説明を書いていることに気付いた場合は、説明するコードとともに、テキストが実際にコメントに属していないかどうかを注意深く検討する必要があります。正しく行う方法の例を次に示します。

   (consume_count): If `count' is unreasonable, return 0 and don't
    advance input pointer.

そして、`cplus-dem.c`の`consume_count`で

   while (isdigit((unsigned char)**type))
     {
       count *= 10;
       count += **type - '0';
       /* A sanity check.  Otherwise a symbol like
         `_Utf390_1__1_9223372036854775807__9223372036854775'
         can cause this function to return a negative value.
         In this case we just consume until the end of the string.  */
      if (count > strlen(*type))
        {
          *type = save;
          return 0;
        }

これは、たとえば新しい関数が「New Function」というログエントリのみを必要とする理由です。すべての詳細はソースにある必要があります。

変更されたすべてに名前を付ける必要性には、常識的な例外を設けることができます。たとえば、プログラムの残りの部分全体で簡単な変更を必要とする変更（変数の名前変更など）を加えた場合、影響を受けるすべての関数に名前を付ける必要はなく、「すべての呼び出し元が変更された」と言うことができます。シンボルを名前変更する場合は、追跡可能性のために、古い名前と新しい名前の両方に言及することを忘れないでください。例については、r861020を参照してください。

一般的に、識別子で検索してエントリを見つけやすくすることと、網羅的に記述することで時間を浪費したり、読みにくいエントリを作成してしまうことの間には緊張関係があります。上記のガイドラインと最善の判断に基づいて、同僚の開発者に配慮してください。（また、他の人がどのようにログエントリを書いているかを確認するには、"svn log"を使用してください。）

ドキュメントや翻訳に関するログメッセージは、やや緩やかなガイドラインになります。すべてのシンボルを記述する必要はなく、変更が翻訳のような継続的なプロセスにおける単なるインクリメントである場合、すべてのファイル名を記述する必要すらありません。例えば、「マダガスカル語翻訳のさらなる作業」のように、変更を簡単に要約してください。プロジェクトに関わるすべての人が変更を理解できるように、ログメッセージは英語で記述してください。

ブランチをコードの「チェックポイント」として使用しており、レビューの準備ができていないと感じる場合は、'On the 'xxx' branch notice' の後に、ログメッセージの先頭に何らかの通知を記述してください。例えば、

   *** checkpoint commit -- please don't waste your time reviewing it ***

また、そのブランチでの後続のコミットをレビューする必要がある場合は、ログメッセージに適切な「svn diff」コマンドを入力してください。差分は、そのブランチ上の隣接しない2つのコミットを含んでいる可能性が高く、レビュー担当者がどのコミットをレビューすべきかを判断するのに時間を費やす必要がないようにするためです。

貢献者のクレジット ¶

コードの貢献を、一貫性があり、解析可能な方法で記録することは非常に重要です。これにより、誰が活発に貢献しているのか、そして彼らが何に貢献したのかを把握するスクリプトを作成でき、潜在的な新しいコミッターを迅速に見つけることができます。Subversionプロジェクトでは、これを実現するために、ログメッセージ内に人間が読めるが機械で解析可能なフィールドを使用しています。

他の人が書いたパッチをコミットする場合は、行の先頭に "Patch by: " を使用して、作成者を示してください。

   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.

   Patch by: J. Random <jrandom@example.com>

複数の人がパッチを書いた場合は、それぞれを別の行にリストし、各継続行を空白で始めるようにしてください。コミッターでない場合は、名前が分かっている場合は名前とメールアドレスでリストしてください。完全なコミッターと部分的なコミッターは、COMMITTERS（そのファイルの左端の列）から、正規のユーザー名でリストしてください。さらに、実際に変更をコミットする人に対して、「me」は許容される省略形です。

   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.

   Patch by: J. Random <jrandom@example.com>
             Enrico Caruso <codingtenor@codingtenor.com>
             jcommitter
             me

誰かがバグを発見したり、問題を指摘したが、パッチを書かなかった場合は、"Found by: "（または "Reported by: "）で彼らの貢献を示してください。

   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.

   Found by: J. Random <jrandom@example.com>

誰かが有益な提案をしたが、パッチを書かなかった場合は、"Suggested by: " で彼らの貢献を示してください。

   Extend the Contribulyzer syntax to distinguish finds from ideas.

   * www/hacking.html (crediting): Adjust accordingly.

   Suggested by: dlr

誰かがパッチをテストドライブした場合は、"Tested by: " を使用してください。

    Fix issue #23: random crashes on FreeBSD 3.14.
    
    Tested by: Old Platformer
    (I couldn't reproduce the problem, but Old hasn't seen any crashes since
    he applied the patch.)
    
    * subversion/libsvn_fs_sieve/obliterate.c
      (cover_up): Account for sieve(2) returning 6.

誰かが変更をレビューした場合は、"Review by: " (または "Reviewed by: " を好む場合はそちらを使用してください) を使用してください。

   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.

   Review by: Eagle Eyes <eeyes@example.com>

1つのフィールドは複数行にわたることができ、1つのログメッセージには任意の組み合わせのフィールドを含めることができます。

   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.

   Patch by: J. Random <jrandom@example.com>
             Enrico Caruso <codingtenor@codingtenor.com>
             me
   Found by: J. Random <jrandom@example.com>
   Review by: Eagle Eyes <eeyes@example.com>
              jcommitter

貢献に関する詳細情報は、対応するフィールドの直後の括弧で囲まれた補足情報にリストする必要があります。このような補足情報は、常にすぐ上のフィールドに適用されます。次の例では、読みやすくするためにフィールドの間隔を空けていますが、間隔は任意であり、解析のために必須ではありません。

   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.

   Patch by: J. Random <jrandom@example.com>
   (Tweaked by me.)

   Review by: Eagle Eyes <eeyes@example.com>
              jcommitter
   (Eagle Eyes caught an off-by-one-error in the basename extraction.)

現在、これらのフィールド

   Patch by:
   Suggested by:
   Found by:
   Review by:
   Tested by:

は、公式にサポートされている唯一のクレジットフィールドです（「サポートされている」とは、スクリプトがそれらを探すことを認識しているという意味です）。これらはSubversionのログメッセージで広く使用されています。今後のフィールドはおそらく "VERB by: " の形式になり、時々、公式のように聞こえるが実際には公式ではないフィールドを使用する人がいるかもしれません。例えば、 "Inspired by: " のいくつかの例があります。これらは問題ありませんが、独自のフィールドを作成するよりも、公式フィールドまたは括弧で囲まれた補足情報を使用するようにしてください。また、報告者がすでにissueに記録されている場合は、 "Reported by: " を使用しないでください。代わりに、単にissueを参照してください。

Subversionの既存のログメッセージを見て、これらのフィールドを実際にどのように使用するかを確認してください。 trunkのワーキングコピーの最上部からのこのコマンドが役立ちます。

svn log | contrib/client-side/search-svnlog.pl "(Patch|Review|Suggested) by: "

注: 一部のコミットメッセージに見られる "Approved by: " フィールドは、これらのクレジットフィールドとは完全に無関係であり、一般的にスクリプトによって解析されません。これは、通常の部分的なコミッターが自分の通常の領域外でコミットを承認した人、または（リリースブランチへのマージの場合）変更のマージに投票した人を示すための標準的な構文にすぎません。

Github ¶

Subversionリポジトリは、https://github.com/apache/subversion/ でGitHubにミラーリングされています。

一部のユーザーはGitHubでプルリクエストを作成する可能性があります。コードがSubversionリポジトリにコミットされる場合は、ログメッセージにプルリクエストを自動的にクローズするためのテキストを含めるようにしてください。

This fixes #NNN in GitHub

コードをコミットせずにプルリクエストを管理するには、ASF IDに接続されたGitHubアカウントを持ち、トリアージ担当者の役割をASFインフラストラクチャによってあなたのアカウントに割り当てる必要があります。

Unixでの設定/ビルドシステム ¶

Greg Steinは、`automake` と再帰的なMakefileを使用していたSubversion用のカスタムビルドシステムを作成しました。現在、Makefile.in (これはリビジョン管理されています) から生成された単一のトップレベルのMakefileを使用しています。`Makefile.in` は、`build.conf` から `gen-make.py` スクリプトによって自動的に生成される `build-outputs.mk` を含んでいます。したがって、後者の2つはリビジョン管理されていますが、`build-outputs.mk` はリビジョン管理されていません。

以下に、このシステムについて説明したGregの元のメールと、それをハックするためのアドバイスを示します。

   From: Greg Stein <gstein@lyra.org>
   Subject:  new build system (was: Re: CVS update: MODIFIED: ac-helpers ...)
   To: dev@subversion.tigris.org
   Date: Thu, 24 May 2001 07:20:55 -0700
   Message-ID: <20010524072055.F5402@lyra.org>

   On Thu, May 24, 2001 at 01:40:17PM -0000, gstein@tigris.org wrote:
   >   User: gstein
   >   Date: 01/05/24 06:40:17
   >
   >   Modified:    ac-helpers .cvsignore svn-apache.m4
   >   Added:       .        Makefile.in
   >   Log:
   >   Switch over to the new non-recursive build system.
   >...

   Okay... this is it. We're now on the build system.

       "It works on my machine."

   I suspect there may be some tweaks to make on different OSs. I'd be
   interested to hear if Ben can really build with normal BSD make. It
   should be possible.

   The code supports building, installation, checking, and
   dependencies. It does *NOT* yet deal with the doc/ subdirectory. That
   is next; I figured this could be rolled out and get the kinks worked
   out while I do the doc/ stuff.  Oh, it doesn't build Neon or APR yet
   either. I also saw a problem where libsvn_fs wasn't getting built
   before linking one of the test proggies (see below).

   Basic operation: same as before.

   $ ./autogen.sh
   $ ./configure OPTIONS
   $ make
   $ make check
   $ make install

   There are some "make check" scripts that need to be fixed up. That'll
   happen RSN. Some of them create their own log, rather than spewing to
   stdout (where the top-level make will place the output into
   [TOP]/tests.log).

   The old Makefile.am files are still around, but I'll be tossing those
   along with a bunch of tweaks to all the .cvsignore files. There are a
   few other cleanups, too. But that can happen as a step two.

   [ $ cvs rm -f `find . -name Makefile.rm`

     See the mistake in that line? I didn't when I typed it. The find
     returned nothing, so cvs rm -f proceeded to delete my entire
     tree. And the -f made sure to delete all my source files, too. Good
     fugging thing that I had my mods in some Emacs buffers, or I'd be
     bitching.

     I am *so* glad that Ben coded SVN to *not* delete locally modified
     files *and* that we have an "undel" command. I had to go and tweak a
     bazillion Entries files to undo the delete...
   ]

   The top-level make has a number of shortcuts in it (well, actually in
   build-outputs.mk):

   $ make subversion/libsvn_fs/libsvn_fs.la

   or

   $ make libsvn_fs

   The two are the same. So... when your test proggie fails to link
   because libsvn_fs isn't around, just run "make libsvn_fs" to build it
   immediately, then go back to the regular "make".

   Note that the system still conditionally builds the FS stuff based
   on whether DB (See 'Building on Unix' below) is available, and
   mod_dav_svn if Apache is available.

   Handy hint: if you don't like dependencies, then you can do:

   $ ./autogen.sh -s

   That will skip the dependency generation that goes into
   build-outputs.mk. It makes the script run quite a bit faster (48 secs
   vs 2 secs on my poor little Pentium 120).

   Note that if you change build.conf, you can simply run:

   $ ./gen-make.py build.conf

   to regen build-outputs.mk. You don't have to go back through the whole
   autogen.sh / configure process.

   You should also note that autogen.sh and configure run much faster now
   that we don't have the automake crap. Oh, and our makefiles never
   re-run configure on you out of the blue (gawd, I hated when automake
   did that to me).

   Obviously, there are going to be some tweaky things going on. I also
   think that the "shadow" builds or whatever they're called (different
   source and build dirs) are totally broken. Something tweaky will have
   to happen there.  But, thankfully, we only have one Makefile to deal
   with.

   Note that I arrange things so that we have one generated file
   (build-outputs.mk), and one autoconf-generated file (Makefile from
   .in).  I also tried to shove as much logic/rules into
   Makefile.in. Keeping build-outputs.mk devoid of rules (thus, implying
   gen-make.py devoid of rules in its output generation) manes that
   tweaking rules in Makefile.in is much more approachable to people.

   I think that is about it. Send problems to the dev@ list and/or feel
   free to dig in and fix them yourself. My next steps are mostly
   cleanup. After that, I'm going to toss out our use of libtool and rely
   on APR's libtool setup (no need for us to replicate what APR already
   did).

   Cheers,
   -g

   --
   Greg Stein, http://www.lyra.org/

そして、設定/ビルドシステムを変更またはテストするためのアドバイスを以下に示します。

   From: Karl Fogel <kfogel@collab.net>
   To: dev@subversion.tigris.org
   Subject: when changing build/config stuff, always do this first
   Date: Wed 28 Nov 2001

   Yo everyone: if you change part of the configuration/build system,
   please make sure to clean out any old installed Subversion libs
   *before* you try building with your changes.  If you don't do this,
   your changes may appear to work fine, when in fact they would fail if
   run on a truly pristine system.

   This script demonstrates what I mean by "clean out".  This is
   `/usr/local/cleanup.sh' on my system.  It cleans out the Subversion
   libs (and the installed httpd-2.0 libs, since I'm often reinstalling
   that too):

      #!/bin/sh

      # Take care of libs
      cd /usr/local/lib || exit 1
      rm -f APRVARS
      rm -f libapr*
      rm -f libexpat*
      rm -f libneon*
      rm -f libsvn*

      # Take care of headers
      cd /usr/local/include || exit 1
      rm -f apr*
      rm -f svn*
      rm -f neon/*

      # Take care of headers
      cd /usr/local/apache2/lib || exit 1
      rm -f *

   When someone reports a configuration bug and you're trying to
   reproduce it, run this first. :-)

   The voice of experience,
   -Karl

自動テスト ¶

Subversionの自動テストフレームワークを使用および追加する方法については、subversion/tests/README および subversion/tests/cmdline/README を参照してください。

ビルドファーム ¶

ASFインフラストラクチャチームは、BuildBotビルド/テストファームを管理しています。SubversionプロジェクトのBuildbotウォーターフォールは、ここにあります。

• 本番ビルド
• バックポートとRATステータス
• 互換性テスト
• ファーム全体

ビルドサービスの詳細については、ci2.apache.org にアクセスしてください。

buildbotのビルドとテストの失敗に関する通知を受信したい場合は、notifications@ メーリングリストを購読してください。

Buildbotは、インフラストラクチャリポジトリ、具体的には subversion.py ファイルで構成されています。

コードの前にテストケースを書く ¶

From: Karl Fogel <kfogel@collab.net>
Subject: writing test cases
To: dev@subversion.tigris.org
Date: Mon, 5 Mar 2001 15:58:46 -0600

Many of us implementing the filesystem interface have now gotten into
the habit of writing the test cases (see fs-test.c) *before* writing
the actual code.  It's really helping us out a lot -- for one thing,
it forces one to define the task precisely in advance, and also it
speedily reveals the bugs in one's first try (and second, and
third...).

I'd like to recommend this practice to everyone.  If you're
implementing an interface, or adding an entirely new feature, or even
just fixing a bug, a test for it is a good idea.  And if you're going
to write the test anyway, you might as well write it first. :-)

Yoshiki Hayashi's been sending test cases with all his patches lately,
which is what inspired me to write this mail to encourage everyone to
do the same.  Having those test cases makes patches easier to examine,
because they show the patch's purpose very clearly.  It's like having
a second log message, one whose accuracy is verified at run-time.

That said, I don't think we want a rigid policy about this, at least
not yet.  If you encounter a bug somewhere in the code, but you only
have time to write a patch with no test case, that's okay -- having
the patch is still useful; someone else can write the test case.

As Subversion gets more complex, though, the automated test suite gets
more crucial, so let's all get in the habit of using it early.

-K

SVN_DBGを使用したデバッグ ¶

SVN_DBGデバッグツールは、Cプリプロセッサマクロであり、(デフォルトでは)標準出力、または標準エラー出力にデバッグ出力を送信しながら、SVNテストスイートを妨害しないようにします。

gdbのようなデバッガの代わりになるか、またはデバッガの使用を支援するための追加情報を提供します。デバッガを使用できない状況で特に役立つ可能性があります。

svn_debugモジュールには、呼び出しのファイル：行と、#SVN_DBG_OUTPUT stdioストリーム（デフォルトでは#stdout）へのprintfのような引数を出力する2つのデバッグ支援マクロが含まれています。

SVN_DBG( ( const char *fmt, ...) ) /* double braces are neccessary */

SVN_DBG_PROPS( ( apr_hash_t *props, const char *header_fmt, ...) )

SVN_DBG出力の制御

• SVN_DBGは、svnが--enable-maintainer-modeで構成されている場合は常に有効になります。
• SVNテストスイートはSVN_DBG出力を自動的にオフにします。手動で出力を抑制するには、シェル環境でSVN_DBG_QUIET変数を1に設定します。
• 完了したら、コミットするコードやリストに送信するパッチから、SVN_DBG およびSVN_DBG_PROPS マクロのインスタンスを必ず削除してください。（別名：患者にメスを忘れないでください！）

SVN_DBGマクロの定義とコードは、

• subversion/include/private/svn_debug.h
• subversion/libsvn_subr/debug.c

SVN_DBGマクロの使用を示すサンプルパッチ

Index: subversion/libsvn_fs_fs/fs_fs.c
===================================================================
--- subversion/libsvn_fs_fs/fs_fs.c     (revision 1476635)
+++ subversion/libsvn_fs_fs/fs_fs.c     (working copy)
@@ -2303,6 +2303,9 @@ get_node_revision_body(node_revision_t **noderev_p
 
   /* First, try a cache lookup. If that succeeds, we are done here. */
   SVN_ERR(get_cached_node_revision_body(noderev_p, fs, id, &is_cached, pool));
+  SVN_DBG(("Getting %s from: %s\n", 
+           svn_fs_fs__id_unparse(id),
+           is_cached ? "cache" : "disk"));
   if (is_cached)
     return SVN_NO_ERROR;

SVN_DBG_PROPSマクロの使用を示すサンプルパッチ

Index: subversion/svn/proplist-cmd.c
===================================================================
--- subversion/svn/proplist-cmd.c	(revision 1475745)
+++ subversion/svn/proplist-cmd.c	(working copy)
@@ -221,6 +221,7 @@ svn_cl__proplist(apr_getopt_t *os,
                                       URL, &(opt_state->start_revision),
                                       &rev, ctx, scratch_pool));
+      /*  this can be called with svn proplist  --revprop -r <rev> */
+      SVN_DBG_PROPS((proplist,"The variable apr_hash_t *proplist contains: "));
       if (opt_state->xml)
         {
           svn_stringbuf_t *sb = NULL;

サーバーのデバッグ ¶

   % gdb httpd
   (gdb) run -X
   ^C
   (gdb) break some_func_in_mod_dav_svn
   (gdb) continue

   /usr/local/apache2/logs/error_log
   /usr/local/apache2/logs/access_log

  svn: Malformed network data
  svn: Connection closed unexpectedly

  % gdb svn
  (gdb) break marshal.c:NNN
  (gdb) run ARGS
  Breakpoint 1, vparse_tuple (list=___, pool=___, fmt=___, 
    ap=___) at subversion/libsvn_ra_svn/marshal.c:NNN
  NNN                                 "Malformed network data");

  % gdb svnserve
  (gdb) break marshal.c:NNN
  (gdb) run -X

ネットワークトラフィックのトレース ¶

クライアントとサーバー間のネットワークトラフィックをトレースすることは、デバッグに役立つ場合があります。ネットワークトレースを実行する方法はいくつかあります (このリストは網羅的なものではありません)。

ネットワークトレースを実行するときは、圧縮を無効にするとよいでしょう。—http-compressionパラメーターをservers設定ファイルで確認してください。

svn ls http://example.com/svn/repos/trunk \
    --config-option servers:global:http-proxy-host=localhost \
    --config-option servers:global:http-proxy-port=9630 \
    --config-option servers:global:http-compression=no

メモリリークの追跡 ¶

APR プールの使用により、厳密な意味でのメモリリークが発生することはまれです。割り当てたすべてのメモリは最終的にクリーンアップされます。ただし、操作によって必要以上のメモリが使用されることがあります。たとえば、大きなソースツリーのチェックアウトでは、小さなソースツリーのチェックアウトよりも多くのメモリを使用すべきではありません。それが起こる場合は、通常、有効期間が長すぎるプールからメモリを割り当てていることを意味します。

お気に入りのメモリリーク追跡ツールがある場合は、--enable-pool-debug (これにより、すべてのプール割り当てが独自の malloc() を使用するようになります) を使用して設定し、操作の途中で終了するように設定して、そこに移動できます。そうでない場合は、別の方法を示します。

• --enable-pool-debug=verbose-alloc を使用して設定します。すべての割り当てでファイルと行の情報が取得されるように、APR と Subversion のすべてを再構築してください。

• 操作を実行し、stderr をファイルにパイプ処理します。うまくいけば、十分なディスク容量があるでしょう。

• ファイルには、次のような多くの行が表示されます。

      POOL DEBUG: [5383/1024] PCALLOC (      2763/      2763/      5419) \
      0x08102D48 "subversion/svn/main.c:612"                             \
      <subversion/libsvn_subr/auth.c:122> (118/118/0)
     

  最も重要なのは 10 番目のフィールド (引用符で囲まれたもの) で、この割り当てのプールが作成されたファイルと行番号を示します。そのファイルと行に移動して、プールの有効期間を確認します。上記の例では、main.c:612 は、この割り当てが svn クライアントの最上位プールで行われたことを示しています。これが、操作中に何度も繰り返された割り当てである場合、メモリリークの原因を示します。11 番目のフィールド (括弧で囲まれたもの) は、割り当て自体のファイルと行番号を示します。

メーリングリスト ¶

• 投稿先
• 投稿するタイミング
• フォーマット
• 返信
• パッチの送信
• 言語とエンコーディング

以下のアドバイスは、Subversionメーリングリストでの長年の経験に基づいており、それらのリストで最も頻繁に見られる問題に対処しています。これはメーリングリストのエチケットに関する完全なガイドではありません。必要に応じて、インターネットで簡単に見つけることができます。

メーリングリストに投稿するときにこれらの規則に従うと、投稿が読まれ、回答される可能性がはるかに高くなります。

   Blue asparagus
     |
     |_ Re: Blue asparagus
         |
         |_ Yellow elephants (was: Re: Blue asparagus)    <-- ### switch ###
            |
            |_ Re: Yellow elephants

バグ/問題 ¶

• バグの報告方法
• バグの報告先
• マイルストーン管理
• 問題のトリアージ
• セキュリティ

Subversionは完璧なソフトウェアではありません。他のソフトウェアと同様に、バグが含まれ、機能が不足しており、改善の余地があります。ほとんどのソフトウェアプロジェクトと同様に、Subversionプロジェクトでは、ソフトウェアの既知の未解決の問題を管理するために問題追跡ツールを使用しています。しかし、おそらくほとんどのソフトウェアプロジェクトとは異なり、問題追跡ツールを比較的デブリがない状態に保とうとしています。Subversionの問題について聞きたくないわけではありません。結局のところ、壊れていることを知らないものを修正することはできません。混乱した問題追跡ツールは、助けになるよりもむしろ妨げになることがわかっています。

このメールは、すべてを語っています（ただし、最近はdev@リストに投稿する前にusers@リストに投稿する必要があります）。

   From: Karl Fogel <kfogel@collab.net>
   Subject: Please ask on the list before filing a new issue.
   To: dev@subversion.tigris.org
   Date: Tue, 30 Jul 2002 10:51:24 (CDT)
   
   Folks, we're getting tons of new issues, which is a Good Thing in
   general, but some of them don't really belong in the issue tracker.
   They're things that would be better solved by a quick conversation
   here on the dev list.  Compilation problems, behavior questions,
   feature ideas that have been discussed before, that sort of thing.
   
   *Please* be more conservative about filing issues.  The issues
   database is physically much more cumbersome than email.  It wastes
   people's time to have conversations in the issues database that should
   be had in email.  (This is not a libel against the issue tracker, it's
   just a result of the fact that the issues database is for permanent
   storage and flow annotation, not for real-time conversation.)
   
   If you encounter a situation where Subversion is clearly behaving
   wrongly, or behaving opposite to what the documentation says, then
   it's okay to file the issue right away (after searching to make sure
   it isn't already filed, of course!).  But if you're
   
      a) Requesting a new feature, or
      b) Having build problems, or
      c) Not sure what the behavior should be, or
      d) Disagreeing with current intended behavior, or
      e) Not TOTALLY sure that others would agree this is a bug, or
      f) For any reason at all not sure this should be filed,
   
   ...then please post to the dev list first.  You'll get a faster
   response, and others won't be forced to use the issues database to
   have the initial real-time conversations.
   
   Nothing is lost this way.  If we eventually conclude that it should be
   in the issue tracker, then we can still file it later, after the
   description and reproduction recipe have been honed on the dev list.
   
   Thank you,
   -Karl

以下は、Subversionへの問題の報告または機能拡張の要求時に遵守をお願いするポリシーです。

    for i in issues_marked_as("---"):
      if issue_is_a_dup_of_some_other_issue(i):
        close_as_dup(i)
      elif issue_is_invalid(i):
        # A frequent reason for invalidity is that the reporter
        # did not follow the "buddy system" for filing.
        close_as_invalid(i)
      elif issue_already_fixed(i):
        version = fixed_in_release(i)
        move_to_milestone(i, version)
        close_as_fixed(i)
      elif issue_unreproducible(i):
        close_as_worksforme(i)
      elif issue_is_real_but_we_won't_fix_it(i):
        close_as_wontfix(i)
      elif issue_is_closeable_for_some_other_reason(i):
        close_it_for_that_reason(i)

      # Else issue should remain open, so DTRT with it...

      # Set priority, environment, component, etc, as needed.
      adjust_all_fields_that_need_adjustment(i)

      # Figure out where to put it.
      if issue_is_a_lovely_fantasy(i):
        move_to_milestone(i, "blue-sky")
      if issue_is_not_important_enough_to_block_any_particular_release(i):
        move_to_milestone(i, "nonblocking")
      elif issue_resolution_would_require_incompatible_changes(i):
        move_to_milestone(i, "2.0-consider")
      elif issue_hurts_people_somewhat(i):
        move_to_milestone(i, "1.6-consider")  # or whatever
      elif issue_hurts_people_a_lot(i):
        move_to_milestone(i, "1.5-consider")
      elif issue_hurts_and_hurts_and_should_block_the_release(i):
        move_to_milestone(i, "1.5")

Subversionリリースの作成 ¶

• Subversionリリースプロセス
• リリース番号
• リリース間の互換性
• カスタムリリース
• 非推奨
• リリースの安定化と保守
• Subversionリリースの作成
• 翻訳者に通知する
• リリースをロールバックする準備
• リリースをロールバックする
• ソースディストリビューションパッケージ（別名tarball）に署名する
• 実際のリリースの実施
• リリースブランチの作成と保守
• 新しいマイナーリリースブランチを作成する準備
• 新しいマイナーリリースブランチを作成する
• リリースブランチへの変更の移植
• CHANGESファイルの管理
• ブランチの初期コンテンツを記述する
• パッチリリース用のコンテンツを追加する
• Subversionリリースを作成しない方法

このドキュメントは、一般に、具体性が増す順に3つの部分に分けることができます。

• バージョン番号や互換性などの、高レベルのリリース計画とポリシー。「tarballはいつ作成されるのか？」や「tarballの内容はどうあるべきか？」といった質問に答えます。
• リリースを作成する際に取るべき手順。「リリースをどのように管理すればよいか？」という質問に対処します。
• リリースtarballのセットを構築する方法。このセクションでは、リポジトリ内のソースコードから配布可能な一連のファイルを作成するために必要な手順について説明します。.tar.gzまたは.zip望ましい内容を含むファイル。

Subversionのリリース管理者は、release.pyという名前のPythonスクリプトに体系化された一連の手順を使用します。このスクリプトは、リリースプロセスの自動化された手順のほとんどを実行するために使用できます。詳細については、-hオプションを指定して実行してください。

以下のプロジェクト固有のガイドラインに加えて、リリース管理者を目指す人は、一般的なApacheリリースポリシーも読むと良いでしょう。 時には少しパッチワークのように見えるかもしれませんが、一般的なベストプラクティスと、Subversionがより大きなASFエコシステムにどのように適合するかについて、良いアイデアを得ることができます。

   1.0.1  -->  first stable patch release of 1.0
   1.1.0  -->  next stable minor release of 1.x after 1.0.x
   1.1.1  -->  first stable patch release of 1.1.x
   1.1.2  -->  second stable patch release of 1.1.x
   1.2.0  -->  next stable minor release after that

   version 1.7.1-dev (under development)

   /**
    * Similar to svn_repos_dump_fs3(), but with a @a feedback_stream instead of
    * handling feedback via the @a notify_func handler
    *
    * @since New in 1.1.
    * @deprecated Provided for backward compatibility with the 1.6 API.
    */
   SVN_DEPRECATED
   svn_error_t *
   svn_repos_dump_fs2(svn_repos_t *repos,
                      svn_stream_t *dumpstream,
                      svn_stream_t *feedback_stream,
                      svn_revnum_t start_rev,
                      svn_revnum_t end_rev,
                      svn_boolean_t incremental,
                      svn_boolean_t use_deltas,
                      svn_cancel_func_t cancel_func,
                      void *cancel_baton,
                      apr_pool_t *pool);

   * r98765 (issue #56789)
     Make commit editor take a closure object for future mindreading.
     Justification:
       API stability, as prep for future enhancement.
     Branch: 1.8.x-r98765
     Notes:
       There was consensus on the desirability of this feature in
       the near future; see thread at http://... (Message-Id: blahblah).
       Merge with --accept=mc.
     Concerns:
       Vetoed by jerenkrantz due to privacy concerns with the
       implementation; see thread at http://... (Message-Id: blahblah)
     Votes:
       +1: ghudson, bliss
       +0: cmpilato
       -0: gstein
       -1: jerenkrantz

 * r31833
   svndumpfilter: Don't match prefixes to partial path components.
   Fixes #desc4 of issue #1853.
   Votes:
     +1: danielsh, hwright
     +1 (non-binding): stylesen

   * r30643, r30653, r30785
     Update bash completion script.
     Votes:
       +1: arfrever (r30785 only), stylesen

sed -e '/^ *Translat.*:$/,/:$/!d' -e 's/^ *[^ ]* *\([^>]*>\).*/\1/;t;d' COMMITTERS

./tools/po/l10n-report.py

mkdir -p /opt/svnrm && cd /opt/svnrm && $SVN_SRC_DIR/tools/dist/release.py build-env X.Y.Z

./release.py roll X.Y.Z 1234

    a) tar zxvf subversion-X.Y.Z.tar.gz;  cd subversion-X.Y.Z
    b) ./configure
 
       See INSTALL, section III.B for detailed instructions on
       configuring/building Subversion.
 
       If you installed Apache in some place other than the default, as
       mentioned above, you will need to use the same
       --prefix=/usr/local/apache2 option as used to configure Apache.
 
       You may also want to use --enable-mod-activation, which will
       automatically enable the required Subversion modules in the
       Apache config file.
 
    c) make
    d) make check
    e) make install (this activates mod_dav)
    f) make davcheck
 
       For this, start up Apache after having configured according to
       the directions in subversion/tests/cmdline/README.
 
       Make sure, that if you maintain a development installation of
       apache, that you check the config file and update it for the
       new release area where you're testing the tar-ball.
 
       (Unless you rename the tree which gets extracted from the
       tarball to match what's in httpd.conf, you will need to edit
       httpd.conf)
 
    g) make svncheck
 
       First, start up svnserve with these args:
 
          $ subversion/svnserve/svnserve -d -r \
            `pwd`/subversion/tests/cmdline
 
       -d tells svnserve to run as a daemon
       -r tells svnserve to use the following directory as the
          logical file system root directory.
 
       After svnserve is running as a daemon 'make svncheck' should run
 
    h) Then test that you can check out the Subversion repository
       with this environment:
 
          subversion/svn/svn co https://svn.apache.org/repos/asf/subversion/trunk
 
    i) Verify that the perl, python, and ruby swig bindings at least compile.
       If you can't do this, then have another developer verify.
 
       (see bindings/swig/INSTALL for details)
 
       Ensure that ./configure detected a suitable version of swig,
       perl, python, and ruby.  Then:
 
          make swig-py
          make check-swig-py
          sudo make install-swig-py
 
          make swig-pl
          make check-swig-pl
          sudo make install-swig-pl
 
          make swig-rb
          make check-swig-rb
          sudo make install-swig-rb

    j) Verify that the javahl bindings at least compile.
       If you can't do this, then have another developer verify.
 
       (see subversion/bindings/javahl/README for details)
 
       Ensure that ./configure detected a suitable jdk, and then
       possibly re-run with '--enable-javahl', '--with-jdk=' and
       '--with-junit=':
 
          make javahl
          sudo make install-javahl
          make check-javahl

    k) Verify that the ctypes python bindings at least compile.
       If you can't do this then have another developer verify.

       (see subversion/bindings/ctypes-python/README for details)

       Ensure that ./configure detected a suitable ctypesgen, and
       then possibly re-run with '--with-ctypesgen':

          make ctypes-python
          sudo make install-ctypes-python
          make check-ctypes-python 

    l) Verify that get-deps.sh works and does not emit any errors.

          ./get-deps.sh

    release.py sign-candidates X.Y.Z

    gpg -ba subversion-X.Y.Z.tar.bz2
    gpg -ba subversion-X.Y.Z.tar.gz
    gpg -ba subversion-X.Y.Z.zip

    release.py create-tag X.Y.Z 1234

release.py post-candidates 1.7.0

    release.py get-keys
    release.py --target /path/to/dist/dev/subversion/wc check-sigs 1.7.0-rc4

    gpg -ba -o - subversion-1.7.0-rc4.tar.bz2 >> subversion-1.7.0-rc4.tar.bz2.asc

 release.py --target /path/to/dist/dev/subversion/wc sign-candidates 1.7.0-rc4

    bzip2 -cd subversion-1.7.0-rc4.tar.bz2 \
    | gzip -9n > subversion-1.7.0-rc4.tar.gz

release.py move-to-dist 1.7.0

release.py clean-dist

curl -u USERNAME "https://reporter.apache.org/addrelease.py?date=`date +%s`&committee=subversion&version=VERSION&xdate=`date +%F`"

release.py --verbose create-release-branch A.B.0

release.py --verbose write-release-notes A.B.0 > .../docs/release-notes/A.B.html
svn add .../docs/release-notes/A.B.html
svn ci -m "Add release notes template." .../docs/release-notes/A.B.html

svn checkout --depth=empty https://svn-master.apache.org/repos/asf/subversion/branches ~svnsvn/src/svn
svn up ~svnsvn/src/svn/A.B.x  # for each supported branch

sudo -H -u svnsvn  svn up ~svnsvn/src/svn/A.B.x

sudo -H -u svnsvn  svn up -r0 ~svnsvn/src/svn/Z.Z.x

release.py write-changelog

ローカライゼーション (l10n) ¶

• ローカライゼーションの概要
• ソフトウェアバージョンの要件
• 新しい翻訳の開始
• poファイルの検証
• poファイルの提出
• 既存のpoファイルの更新
• ブランチのメンテナンス
• poファイルとmoファイルの要件
• 空の文字列msgidセクションの規約
• 翻訳チーム
• シングルクォートとダブルクォート
• エラーメッセージの規約

翻訳は2つの領域に分けられています。1つ目は、接続しているクライアントに送信されるサーバーメッセージの翻訳です。この問題は、今のところ先送りにされています。2つ目は、クライアントとそのライブラリの翻訳です。

   #include "svn_private_config.h"

  # SOME DESCRIPTIVE TITLE.
  # Copyright (C) YEAR THE PACKAGE'S COPYRIGHT HOLDER
  # This file is distributed under the same license as the PACKAGE package.
  # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.

  # <Your language> translation for subversion package
  #    Licensed to the Apache Software Foundation (ASF) under one
  #    or more contributor license agreements.  See the NOTICE file
  #    distributed with this work for additional information
  #    regarding copyright ownership.  The ASF licenses this file
  #    to you under the Apache License, Version 2.0 (the
  #    "License"); you may not use this file except in compliance
  #    with the License.  You may obtain a copy of the License at
  #
  #      https://apache.dokyumento.jp/licenses/LICENSE-2.0
  #
  #    Unless required by applicable law or agreed to in writing,
  #    software distributed under the License is distributed on an
  #    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  #    KIND, either express or implied.  See the License for the
  #    specific language governing permissions and limitations
  #    under the License.

  "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
  "Language-Team: LANGUAGE <LL@li.org>\n"

  "Last-Translator: Subversion Developers <dev@subversion.apache.org>\n"
  "Language-Team: YOUR LANGUAGE <dev@subversion.apache.org>\n"

    make locale-gnu-po-update

    make locale-gnu-po-update PO=ll

  svn cat -r X ^/subversion/trunk/subversion/po/YY.po | \
    po-merge.py YY.po