<!--
     The FreeBSD Documentation Project
     The FreeBSD Japanese Documentation Project

     Original revision: 1.28
     $FreeBSD$
-->

<chapter id="policies">
   <chapterinfo>
     <authorgroup>
       <firstname>Poul-Henning</firstname>
       <surname>Kamp</surname>
       <contrib>寄稿: </contrib>
     </authorgroup>
   </chapterinfo>

   <title>ソースツリーのガイドラインおよび方針</title>

  <para><emphasis>訳者: &a.jp.mihoko;、1996 年 9 月 6 日</emphasis></para>

  <para>本章は、FreeBSD
    のソースツリーについてのさまざまなガイドラインや
    ポリシーについて書かれています。</para>

  <sect1 id="policies-maintainer">
    <title>Makefile 中の <makevar>MAINTAINER</makevar></title>
    <indexterm><primary>port 保守担当 (ports maintainer)</primary></indexterm>

    <para>1996 年 6 月</para>

    <para>FreeBSD 配布物の特定の部分が、一人の人やグループによって保守
      されている場合は、ソースツリーの当該
      <filename>Makefile</filename> に

      <programlisting>MAINTAINER= email-addresses</programlisting>

      が付け加えられています。これを記述することによって、
      この部分が誰によって保守管理されているかを世界中のユーザに
      伝えることができます。</para>

    <para>この意味は次のとおりです:</para>

    <para>保守担当者がそのコードを所有し、そのコードに対する責任を持っ
      ています。すなわち、
      その人がそのコードに関するバグの修正やトラブル報告
      に対する回答をします。また、
      そのコードが寄贈ソフトウェアの場合には、そのソフトウェアの
      新しいバージョンに適切に追従させる作業をその人が行い
      ます。</para>

    <para>保守担当者が決められているディレクトリに対して
      変更をおこなう場合は、変更をおこなう前に、
      その変更内容を保守担当者に送って、
      保守担当者にレビューをしてもらってください。保守担当者が、
      電子メールに一定期間応答しない場合にのみ、
      保守担当者がレビューすることなしに、
      変更をおこなうことが認められます。しかしながら、
      そのような場合でも可能な限り、変更点を第三者にレビュー
      してもらうようにしてください。</para>

    <para>もちろん、この義務を引き受けることができない人やグループを
      保守管理者として追加することはできません。また、
      保守管理者がソースツリー管理者 ("committer") である必要は
      ありません。</para>
  </sect1>

  <sect1 id="policies-contributed">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Poul-Henning</firstname>
	  <surname>Kamp</surname>
	  <contrib>寄稿: </contrib>
	</author>
	<author>
	  <firstname>David</firstname>
	  <surname>O'Brien</surname>
	</author>
      </authorgroup>
      <!-- June 1996 -->
    </sect1info>

    <title>寄贈ソフトウェア</title>
    <indexterm><primary>寄贈ソフトウェア</primary></indexterm>

    <para><emphasis>訳者: &a.jp.mihoko;</emphasis></para>


    <para>FreeBSD 配布物のうちのいくつかのソフトウェアは FreeBSD
      プロジェクト以外のところで保守されています。歴史的な経緯から、
      私たちはこれを <emphasis>寄贈</emphasis> ソフトウェアと
      呼んでいます。<command>perl</command> や <command>gcc</command>
      <command>patch</command> などがその例です。</para>

    <para>ここ数年来、この種のソフトウェアの取り扱いには、
      さまざまな方法が 取られてきましたが、
      どの方法にもいくつかの利点と欠点があります。
      これまで欠点のない明確な方法はありませんでした。</para>

    <para>議論した結果、これらの方法のうちの一つが
      <quote>公式な</quote> 方法として選択されました。その方法が、今後、
      この種のソフトウェアを取り込む場合に、使用されます。その上、
      この方法では、だれもが (cvs
      にアクセス権のない人でさえ) <quote>公式</quote>
      バージョンのソースに対する差分を簡単に得ることができます。
      これは古い方法にはなかった大きな利点です。ですから、
      既存の寄贈ソフトウェアも、
      この方法に収束していくことを強く望んでいます。
      この方法を使用することにより、寄贈ソフトウェアの主な開発者に、
      変更点を返すのがとても容易になります。</para>

    <para>しかしながら結局、寄贈ソフトウェアの取扱は、
      実際に作業を行っている人々に委ねられています。
      もしこの方法を使用することが、その人が扱っているパッケージには
      極端に合わないような場合には、コアチームの承認さえあれば、
      これらのルールに反しても、
      他の開発者の一般的な合意は得られるでしょう。
      将来にわたってパッケージを保守できるということは、
      大変重要な事柄に なってきます。</para>

    <note>
      <para>RCS のファイルフォーマットと CVS
	のベンダブランチの使用には不幸な設計上の制限があります。
	したがって、
	ベンダブランチの内容をいまだに引きずっているファイルに
	対して小さな、些細な変更、そして / あるいは
	膨大な変更を加えることには、
	<emphasis>強い反対があります</emphasis>。
	<quote>誤字訂正</quote> はもちろんこの中に入りますし、<!--
	kuriyama - cosmetic? -->
	しかも <quote>膨大な</quote> の範疇に入るので、リビジョンが
	1.1.x.x
	であるファイルに対する誤字訂正は避けられることになっています。
	一文字の変更したことによるリポジトリの肥大は、
	非常に劇的なものになり得るのです。</para>
    </note>

    <para>プログラミング言語 <application>Tcl</application> は、
      この方法が活用されているよい例になっています:</para>

    <para><filename>src/contrib/tcl</filename> には、
      このパッケージの保守管理者が配布したソースが含まれています。
      この中からは FreeBSD に完全には適用
      できない部分が削除されています。Tcl の場合は、
      <filename>mac</filename>、<filename>win</filename>、
      <filename>compat</filename> というサブディレクトリは、FreeBSD
      に取り込む前に削除されていました。</para>

    <para><filename>src/lib/libtcl</filename> には、
      ライブラリを生成したり、ドキュ
      メントをインストールする際に使用される、標準の
      <filename>bsd.lib.mk</filename> の規則を使用した
      <command>bmake</command> スタイルの
      <filename>Makefile</filename> だけが含まれています。</para>

    <para><filename>src/usr.bin/tclsh</filename> には、
      <filename>bsd.prog.mk</filename> 規則を使用して、
      <command>tclsh</command>
      プログラムや関連するマニュアルページを生成 / インストールする
      bmake スタイルの <filename>Makefile</filename>
      だけが含まれています。</para>

    <para><filename>src/tools/tools/tcl_bmake</filename> には、Tcl
      ソフトウェアを更新する必要が生じたときの助けになる 2 つのシェルス
      クリプトが含まれています。これらは、
      ソフトウェアを構築するのに使用したり、
      インストール対象になるソフトウェアではありません。</para>

    <para>ここ重要なのは、<filename>src/contrib/tcl</filename>
      ディレクトリが、規則にしたがっ て作られているということです。
      つまり、できるだけ FreeBSD に特化した
      変更をおこなわないようにしたソースを (RCS
      のキーワードを拡張しないで、CVS のベンダブランチに) おくようにし
      ています。<!-- kuriyama - easyimport -->
      <hostid>freefall</hostid> 上の「簡易取り込み」ツールは、
      寄贈ソフトウェアを取り込む手助けとなります。けれども、
      このツールの実行方法に疑問が生じた場合は、まずはじめに質問して、
      失敗をしないようにしてください。そして、
      その疑問を <quote>解決して</quote> からツールを使用してください。
      CVS に寄贈ソフトウェアを取り込む際には、
      事故があってはいけません。
      よくあるような間違いをおかさないように、
      十分注意してください。</para>

    <para>先ほど述べたように、残念なことに CVS
      にはベンダブランチという設計制限があります。このため、CVS
      に寄贈ソフトウェアを取り込むには、オリジナル配布ソースに
      適用されるベンダからの <quote>公式</quote> パッチと、
      ベンダブランチに逆輸入された 結果が必要です。
      ベンダブランチの一貫性を破壊したり、将来、
      新しいバージョンを取り込む
      時に衝突を起こしてしまったりというような
      困難な事態に陥らないようにしなければなりません。そのために、
      FreeBSD が管理しているバージョンに対して、
      公式パッチを決して当ててはいけませんし、公式パッチを  "commit"
      してはいけません。</para>

    <para>多くのパッケージが、他のアーキテクチャや他の環境と FreeBSD
      との互換性を保ためのファイルをいくつか含んでいます。そこで、
      スペースを節約するために、FreeBSD
      にとっては無意味な配布ツリー上の一
      部を削除することが許されています。けれども、
      削除されずに残ったファイルに対する、著作権の通知やリリース
      ノートのような情報を含んだファイルは、決して削除しては
      <emphasis>いけません</emphasis>。</para>

    <para><command>bmake</command> <filename>Makefile</filename>
      が何らかのユーティリティによって、配布ツリー
      から自動的に生成できると、うまくいけば、新しいバージョンへの
      アップグレードをより簡単におこなうことができます。
      もしこのようなユーティリティを作成できた場合には、将来の管理者に
      とって便利になるように、移植の際に、
      <filename>src/tools</filename> ディレクトリ上に、(必要に応じて)
      そのユーティリティを必ずチェックインしてください。</para>

    <para><filename>src/contrib/tcl</filename>
      レベルのディレクトリには、<filename>FREEBSD-upgrade</filename>
      と 呼ばれるファイルが追加されており、そのファイルでは
      次のような内容が記述されています。</para>

    <itemizedlist>
      <listitem>
	<para>ディレクトリ上に存在するファイル</para>
      </listitem>

      <listitem>
	<para>オリジナルの配布物をどこから入手すればよいか また、
	  公式配布 サイトはどこか</para>
      </listitem>

      <listitem>
	<para>オリジナルの作者にパッチを送り返すためには、
	  どこに送ればよいか</para>
      </listitem>

      <listitem>
	<para>FreeBSD に特化した変更点の概要</para>
      </listitem>
    </itemizedlist>

    <para>しかしながら、寄贈ソースと一緒に
      <filename>FREEBSD-upgrade</filename> ファイルを
      取り込まないでください。それよりむしろ、
      (訳注: このファイルを) 初回に取り込んだ後は、コマンド <command>cvs
	add FREEBSD-upgrade ; cvs ci</command> を実行してください。
      <filename>src/contrib/cpio</filename> を例にすると、
      次のようになります:</para>

    <programlisting>このディレクトリは「ベンダ」ブランチ上のオリジナル配布ファイル
の初期ソースが含まれています。いかなる事情があっても、
パッチや cvs コミットによってこのディレクトリ上のファイルを
アップグレードしてはいけません。
(訳注: ベンダから配布された) 新しいバージョンや公式パッチだけが
(訳注: このディレクトリに) 取り込まれなくてはいけません。
ベンダの RCS Id が CVS に入ってしまうのを避けるために、"-ko" オプ
ションをつけてインポートすることを忘れないで下さい。

GNU cpio 2.4.2 を取り込むためには、以下のファイルが削除されました:

	INSTALL         cpio.info       mkdir.c
	Makefile.in     cpio.texi       mkinstalldirs

cpio を新しいバージョンにアップデートするためには、次の作業を
おこないます:

	1. 空のディレクトリに新しいバージョンを取り出します。
	   [ファイルに「いかなる変更」も加えてはいけません]

	2. 上記にリストされたファイルと、FreeBSD には無意味な
	   ファイルを削除します。

	3. 次のコマンドを実行します:
		cvs import -ko -m 'Virgin import of GNU cpio v&lt;version&gt;' \
			src/contrib/cpio GNU v&lt;version&gt;

	   たとえば、バージョン 2.4.2 を取り込むためには、次のように
	   タイプします:
		cvs import -ko -m 'Virgin import of GNU v2.4.2' \
			src/contrib/cpio GNU v2.4.2

	4. FreeBSD に対するローカルな変更と、新しいバージョンとの間での
	   矛盾を解消するために、ステップ 3 で出力された命令を実行します。

いかなる事情があっても、この手順から外れてはいけません。

cpio にローカルな変更を加えたい場合には、メインブランチ (別名 HEAD) に対して
パッチを実行し、コミットしてください。
決して GNU のブランチにローカルな変更を加えないでください。

ローカルにおこなわれたすべての変更を次のリリースに含めるために、
"cpio@gnu.ai.mit.edu" に提出してください。

obrien@FreeBSD.org - 30 March 1997</programlisting>
  </sect1>

  <sect1 id="policies-encumbered">
    <title>ソース管理上注意が必要なファイル (Encumbered Files)</title>

    <para> 場合によっては FreeBSD のソースツリーの中にソース管理上
      注意が必要なファイルを含む必要があるかも知れません。例えば、デバイス
      を操作する前に、そのデバイスに小さなバイナリコードをダウンロード
      する必要があり、しかも我々が そのソースコードを持っていない場合、
      そのバイナリファイルのことをソース管理上注意が必要である (encumbered)
      と言います。
      以下に挙げるガイドラインでは、ソース管理上注意が必要なファイルを 
      FreeBSD ソースツリーにいれる方法を示します。
</para>

    <orderedlist>
      <listitem>
        <para>システムの CPU(s) によってインタプリタされたり
          実行されたりするファイルで、しかもソース形式でないファイルは
          すべて、ソース管理上注意が必要なファイルです。</para>
      </listitem>

      <listitem>
        <para>BSD または GNU よりも制限されたライセンスを持つファイルは
        すべて ソース管理上注意が必要なファイルです。</para>
      </listitem>

      <listitem>
        <para>ハードウェアによって使用されるダウンロード可能な
          バイナリコードを含むファイルは、(1) または (2) の条件が
          当てはまらなければ、ソース管理上注意が必要なファイル
          ではありません。
          そのようなファイルはアーキテクチュアに依存しない
          ASCII 形式 (file2c または uuencode が推奨されます) で保存
          します。</para> 
      </listitem>

      <listitem>
        <indexterm><primary>コアチーム (core team)</primary></indexterm>
        <para>ソース管理上注意が必要なファイルはすべて、CVS リポジトリ
        に加える前に、
        <link linkend="staff-core">コアチーム (core team)</link> からの特別な承認
        が必要です。</para>
      </listitem>

      <listitem>
        <para>ソース管理上注意が必要なファイルは <filename>src/contrib</filename> 
        または <filename>src/sys/contrib</filename> に入ります。</para>
      </listitem>

      <listitem>
        <para>すべてのモジュールは一緒に置きます。ソース管理上とくに注意
        を必要としないコードとコードを共有していない限りは、
        モジュールの置場を分ける必要はありません。</para>
      </listitem>

      <listitem>
        <para>オブジェクトファイルは
	  <filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename> と命名されます。</para> 
      </listitem>

      <listitem>
        <para>カーネルファイル</para>

        <orderedlist>
          <listitem>
            <para>必ず
              <filename>conf/files.*</filename> (構築を簡単にするため)
に記述するようにして下さい。</para>
	  </listitem>

          <listitem>
            <para>必ず <filename>LINT</filename> に記述して下さい、
            ただし、それをコメントアウトすべきかどうかは
            <link linkend="staff-core">Core team</link> がその都度
            判断します。
            もちろん <link linkend="staff-core">Core team</link> は
            あとでそれを変更することもできます。</para>
          </listitem>

          <listitem>
            <indexterm><primary>リリースエンジニア (release engineer)</primary></indexterm>
            <para><link linkend="staff-who">リリースエンジニア</link>
             は、それをそのリリースにいれるかどうかを決定します。</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>ユーザランドのファイル</para>

        <orderedlist>
          <listitem>
            <para><link linkend="staff-core">Core team</link> は、そ
            のコードが <command>make world</command> の中で構築される
            べきかどうかを決定します。</para>
          </listitem>
         
          <listitem>
            <para><link linkend="staff-who">リリースエンジニア</link>
              は、それをそのリリースにいれるかどうかを決定します。</para>
          </listitem>
        </orderedlist>
      </listitem>
    </orderedlist>
  </sect1>

  <sect1 id="policies-shlib">
    <sect1info>
      <authorgroup>
	<author>
	  <firstname>Satoshi</firstname>
	  <surname>Asami</surname>
	  <contrib>寄稿: </contrib>
	</author>
	<author>
	  <firstname>Peter</firstname>
	  <surname>Wemm</surname>
	</author>
	<author>
	  <firstname>David</firstname>
	  <surname>O'Brien</surname>
	</author>
      </authorgroup>
      <!-- 9 Dec 1996 -->
    </sect1info>

    <title>共有ライブラリ</title>

    <para>もしあなたが共有ライブラリをサポートする機能を port
      に追加した り、
      共有ライブラリをサポートしていない他のソフトウェアに追加する
      場合には、共有ライブラリのバージョン番号を次の規則にしたがって
      つけてください。一般的には、この規則は、
      ソフトウェアのリリースバージョンとは全く関係ありません。</para>

    <para>共有ライブラリを作成する三つの重要な規則は
      次の通りです:</para>

    <itemizedlist>
      <listitem>
	<para><literal>1.0</literal> から始める</para>
      </listitem>

      <listitem>
	<para>過去のバージョンに互換性のある変更の場合は、
	  マイナー番号を増やす (ELF システムでは
          マイナー番号が無視されることに注意して下さい)</para>
      </listitem>

      <listitem>
	<para>互換性のない変更の場合は、メジャー番号を増やす</para>
      </listitem>
    </itemizedlist>

    <para>例えば、機能追加とバグ吸収の場合は、
      マイナー番号を増やします。機能削除、
      関数呼び出しのシンタックスなどが変更された場合は、
      強制的にメジャー番号を変更します。</para>

    <para>メジャー.マイナーー
      (<replaceable>x</replaceable>,<replaceable>y</replaceable>)
      の形式のバージョン番号を使用します。FreeBSD における
      a.out 形式のダイナミックリンカは、<replaceable>
	x</replaceable>.<replaceable>y</replaceable>.<replaceable>z
      </replaceable> という形式のバージョン番号 は扱えません。
      この場合、<replaceable>y</replaceable> の後のバージョン番号
      (つまり三つ目の数字) は、
      どのライブラリがリンクされているかを決めるために、共有ライブラ
      リ番号を比較する際に、すべて無視されます。
      <quote>小さな</quote> リビジョンだけが
      異なる二つの共有ライブラリが指定 されると、
      <command>ld.so</command> は、
      リビジョンの大きい方の共有ライブラリを リンクします。すなわち、
      もしあなたが <filename>libfoo.so.3.3.3</filename> をリンク
      していたとすると、リンカは頭の <literal>3.3</literal>
      という部分だけを認識し、<replaceable>libfoo.so.3</replaceable>
      ではじまり その後に <replaceable>3
	以上の数字</replaceable>が続くもののうち、
      <replaceable>最も大きい番号</replaceable>
      の付いているライブラリをリンクします。</para>

    <note>
      <para><command>ld.so</command> はいつも最も大きい
	<quote>マイナー</quote> リビジョンのものを使うことに
	注意してください。例えば、プログラムがはじめ
	<filename>libc.so.2.0</filename> を リンクしていたとしても、
	<filename>libc.so.2.0</filename> よりも
	<filename>libc.so.2.2</filename> を優先して使用します。</para>
    </note>

    <para>さらに、ELF ダイナミックリンカはマイナーバージョンを全く扱いません。
      しかし、作成した <filename>Makefile</filename> がそのようなシステムでも
      「きちんと動作できる」ように、メジャー番号およびマイナー番号を
      指定する必要があります。
    </para>

    <para>移植されていないライブラリに対しては、
      共有ライブラリのバージョン番号はリリースごとに一度だけ変更し、
      また、主要な共有ライブラリのバージョン番号は、OS の主リリースごとに
      一度だけ変更する、というのが私たちのポリシーです。
      つまり、X.0 は (X+1).0 になります。
      あなたがシステムライブラリのバージョン番号を上げた場合は、
      <filename>Makefile</filename> の commit ログを確認してください。
      結果としてそのリリースには、共有ライブラリのバージョン番号が
      アップデートされた <filename>Makefile</filename>
      に入るので、最初にその変更を 確かめるのがソースツリー管理者
      ("committer") の責務です。その後のどんな変更も、
      そのリリースには入りません。</para>
  </sect1>
</chapter>

<!--
     Local Variables:
     mode: sgml
     sgml-declaration: "../chapter.decl"
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     sgml-parent-document: ("../book.sgml" "part" "chapter")
     End:
-->
