committer の作業について

motoyuki@FreeBSD.org

注意: このドキュメントの内容はかなり古くなっています。 Resources for FreeBSD Committers などで最新の情報を確認してください。

これは FreeBSD.org の committer としての作業に関する非公式ガイドです。

このガイドは、 浅見さんを始めとする多くの FreeBSD 関係者とのやりとりから生まれたものです。 特に 佐田さん平岡さん の committer 作業に関する Web ページは非常に参考になりました。

目次

  1. 環境設定
    1. アカウントについて
    2. ログインの方法
    3. その他の設定
  2. メールについて
  3. CVS について
    1. 最初の commit
  4. CVS の応用
    1. CVSweb
    2. CVSup
    3. remote CVS
  5. commit 作業の実際
    1. commit する対象を見つける
    2. ports チェックのしかた
    3. CVS でのファイル更新のしかた
    4. 新しい port を登録するには
    5. PR を close する
    6. その他の作業
  6. 細かな注意点

0. はじめに

committer になってしばらくすると、 Eivind Eklund <eivind@yes.no> からメールが届くことと思います。 このメールには committer として作業する上で必須の情報が書かれてるので、 必ず読んでおいてください。 筆者に届いたのは このようなメール でした。

このページでは、 Elvind からのメールだけでは不足しがちな、 committer として作業していくうえでのさまざまな情報を提供していきたいと 考えています。


1. 環境設定

1.1. アカウントについて

まず最初に committer に推薦してくれた コアチーム の方 (恐らく 浅見さん ですよね) に依頼して FreeBSD.org のマシンにアカウントを作成してもらいます。 grep ^USERNAME /etc/master.passwd した結果と希望のアカウント名をメールで送りましょう。 ssh を使用している場合は ~/.ssh/identity.pub も送ったほうがいいでしょう。 FreeBSD ハンドブックの PGP 公開鍵の章 にコアチームメンバの PGP 公開鍵が載っているので、必要ならば PGP で 暗号化して送ることもできます。

FreeBSD.org にあるマシンの解説は The FreeBSD.org Network のページにあります。多くの場合、このうち

freefall.freebsd.org CVS リポジトリがあるマシン。ここで commit を行なう。
hub.freebsd.org メールサーバー
bento.freebsd.org package 作成用

にアカウントが作成されることと思います。 現在のところ、いずれも FreeBSD 3.1-STABLE で運用されています。 これらのマシンの間では home directory は NFS で共有されています。 home directory の実体は freefall にあります。

注: 以前 paddock.freebsd.org という 2.2-stable の package 作成用 マシンがありましたが、こちらは無くなりました。

1.2. ログインの方法

ログインには普通の telnet も使えますが、セキュリティを 考えると ssh(1) の使用をお勧めします。 ssh は FreeBSD の ports/packages に 含まれています。

ssh でログインするには ssh HOSTNAME とします。 telnet と同じくログイン先での passwd が要求されます。

  1. 手元のマシンで ssh-keygen(1) を実行して鍵を作成する。このとき入力する passphrase は非常に重要。
  2. 公開鍵 ~/.ssh/identity.pub を ログイン先の ~/.ssh/authorized_keys にコピーする。
  3. slogin 相手ホスト名 として相手の公開鍵を入手。その後で passphrase を入力するとログインできます。

という手順で passphrase を用いた認証を行うようにしておくと良いでしょう。 ssh-agent(1) を利用すると passphrase 入力を自動化することもできます。 詳しくは ssh のマニュアルを参照してください。

FreeBSD.org のマシンでは ssh の X11 forwarding が有効になっているので、 ssh でログインした状態で xterm などの X のプログラムを起動すれば手元の X に画面が表示されます。

ssh については 佐田さんのページ解説 があります。 また UNIX マガジンの 1998 年 6 - 8 月号にも解説がありました。

1.3. その他の設定

メールの転送についてですが、 ~/.forward では設定できません。 hub.freebsd.org の /var/forward/USERNAME を編集してください。

commit 作業の関係上、 umask は 002 に設定しておいてください。 home directory は各ユーザのみが所属するグループになっていますので、 個人のファイルが他人に書き換えられる心配はありません。

その他の環境設定については普通の FreeBSD マシンと同じです。 ~/public_html/ にファイルを置けば http://www.freebsd.org/~USERNAME/ でアクセスすることができます。 簡単な自己紹介を置いておくことが推奨されているようです。 他のメンバーのホームページは 個人のページ一覧 で参照することができます。


2. メールについて

committer になると自動的に本家の cvs-committers ML に加えられます。 これは cvs-all 相当プラスアルファの内容です。 この ML に CVS に加えられた変更が流れます。

この他に current@freebsd.org と stable@freebsd.org あたりは読んで おいた方がいいと思います。これらは読むのが大変であれば digest 購読 でもいいかもしれません。 ports 関係の作業をするのであれば ports@freebsd.org ML は必ず読んでおく必要があります。

committer としての作業について日本語で気軽に相談できる場所として、 日本の FreeBSD 友の会のサイトに freefall-committers@jp.freebsd.org というメーリングリストがあります。参加アドレス変更等の場合は 今野 <motoyuki@freebsd.org> までメールしてください。 majordomo 経由での変更はできません。


3. CVS について

commit 作業をする際の要です。最近だと UNIX マガジンの 1997 年 11 月号と 1998 年 1, 2 月号に解説があったので、バックナンバーが 手元にあれば参照するといいでしょう。 FreeBSD のソースコードの /usr/src/contrib/cvs/FAQ に英語版の FAQ があります。

CVS では一カ所にある CVS リポジトリ (書庫のようなものです) に ソースコード本体やそこに加えられた変更が全て記録されています。 FreeBSD では freefall.freebsd.org の /home/ncvs に CVS リポジトリが 置かれています。 CVS での作業は基本的に

  1. cvs checkout コマンドで CVS リポジトリからファイルを取り出す。
  2. 取り出したファイルに変更を加える。
  3. cvs commit コマンドで CVS リポジトリに変更を反映させる。

という手順をとります。

3.1. 最初の commit

committer になって最初の commit は FreeBSD ハンドブック開発者 一覧に自分の名前を追加することとなっていますので、 まずは練習としてやってみましょう。 freefall.freebsd.org にログインして適当なディレクトリに移動してください。

cvs -d /home/ncvs checkout doc/handbook

で (英語版) FreeBSD ハンドブックを取り出します。 cd doc/handbook でハンドブックのディレクトリに移動してください。

次にファイルの編集を行います。対象となるのは authors.sgml と contrib.sgml です。他の committer のついての記述を参考にしながら 自分の記述を追加してください。 authors.sgml はログイン名のアルファベット順、 contrib.sgml は last name のアルファベット順であることに注意してください。

Additional FreeBSD Contributors の章に名前がある人が committer になった場合、 Contributors のリストから外すのが慣例となっています。 こちらは submitters.sgml の 700 行目付近にあります。

編集が終わったら、変更点の確認をしましょう。

cvs -d /home/ncvs diff -u .

でどういう変更を行ったかの diff が表示されます。

確認が終わったらいよいよ commit コマンドで変更点を CVS リポジトリに 反映させます。

cvs -d /home/ncvs commit .

を実行します。するとエディタが立ち上がって commit log の入力画面となります。

PR:             
Reviewed by:    
Submitted by:   
Obtained from:
CVS: ----------------------------------------------------------------------
CVS: Obtained from:     Fill this in if the change is from another system.
CVS: Reviewed by:       Fill this in if someone reviewed your modification.
CVS: Submitted by:      Fill this in if someone else sent in the change.
CVS: PR:                Fill this in if a GNATS PR is affected by the change.

のように表示されるはずです。各行の意味は CVS: で始まるコメント行の 通りです。コメント行は実際の commit log には反映されません。 今回の変更は PR: などには関係ないので、これらの行を削除してから

Add myself to the committers.

などと入力してからエディタを終了します。

お疲れさまでした。これで commit 作業は終了です。 変更が CVS リポジトリに反映され commit log が cvs-committers にメールされる様子が表示されるので、 きちんと処理が行われたかどうか確認しておいてください。

FreeBSD ハンドブックの日本語版は doc-jp プロジェクト によって メンテナンスされていますので、日本語版ハンドブックで名前をどのように 表記したらいいか doc-jp@jp.freebsd.org までメールしていただければ幸いです。


4. CVS の応用

4.1. CVSweb

CVS の変更を見るための Web インターフェースとして CVSweb があります。

後者はミラーなので多少更新が遅いです。

4.2. CVSup

手元のマシンに余裕があれば、 CVSup を使って FreeBSD の CVS リ ポジトリ全体を手元のマシンに持ってきておくといいでしょう。 この手順については CVSup を使う を参照してください。技術評論社の「FreeBSD フルコース」の書籍版に非常 に詳しい解説があるので、手元にあれば参照するといいでしょう。

手元のマシンで httpd を走らせている場合は、ローカルで CVSweb を 走らせることもできます。 CVSweb のソースは www/en/cgi/ にあります。作業を進めるのに非常に便利ですので、是非お勧めします。

4.3. remote CVS

前節 では freefall.freebsd.org にログインして作業する 方法を紹介しましたが、これらの作業を自分の手元のマシンで行うこともできます。 それが remote CVS です。

setenv CVS_RSH ssh
cvs -d freefall.freebsd.org:/home/ncvs

環境変数 CVS_RSH に ssh を設定し、 cvs の -d オプションで上のように指定すれば OK です。

筆者の場合、 CVSup を用いてローカルの /home/ncvs に FreeBSD の CVS リポジトリ全体を入手し、 csh の alias で

alias fcvs    cvs -d freefall.freebsd.org:/home/ncvs
alias lcvs    cvs -d /home/ncvs

としています。こうしておくと

  1. lcvs checkout で作業ファイルを checkout
  2. fcvs update で freefall で他の committer が更新していないかチェック
  3. 変更作業を行う。
  4. lcvs diff で変更内容をチェック。
  5. fcvs commit で変更内容を freefall に commit

のように freefall.freebsd.org へのアクセスを最低限に抑えて、 手元でほとんどの作業を行うことができます。


5. commit 作業の実際

5.1. commit する対象を見つける

自分で作成したコードを commit する場合は読み飛ばしてください。

まず、 PR データベース の中から commit するものを選びます。慣れないうちは既存の ports のアップデート あたりから始めるとよいでしょう。 MAINTAINER から send-pr されたものだと 比較的安心です。

パッチなどが ftp://ftp.freebsd.org/pub/FreeBSD/incoming/ に置かれている send-pr が時々あります。ここは悪用を防ぐために directory listing は見えますが get できない状態になっています。こうした場合は、 freebsd-maintainers@wcarchive.cdrom.com にメールして (例えば) /pub/FreeBSD/development/ports/japanese 以下に移動してくれ、 と依頼してください。

5.2. ports チェックのしかた

ports に関する基本的な事項は ports-jp のページ から たどることができます。これらは熟読しておいてください。

ports の開発対象は FreeBSD-current と FreeBSD-stable です。 現在のところ -current, -stable はそれぞれ 4.0-current, 3.0-stable です。 従来の 2.2-stable での動作チェックを行なう必要はありません (チェックを行なってもかまいません)。

まず最初に著作権についてチェックします。 FreeBSD ハンドブックの ports のページ の 4.7.6.節 「ライセンス上の問題」に説明があります。 基本的にはどのような port でも NO_CDROM, NO_PACKAGE, RESTRICTED などを 適切に指定することによって FreeBSD の ports に追加することができます。 疑問点があれば freefall-committers ML などで質問してください。

お決まりの portlint で port の文法をチェックします。 portlint は ports/packages の devel カテゴリ にあります。

次にきちんと build できるかどうかを -current と -stable でチェックします。 make; make install; make package まで正常に実行できるかテストし、かつ インストールされるファイルが pkg/PLIST に漏れなく含まれているか チェックすれば いいでしょう。

手元に -current, -stable マシンがない場合は FreeBSD.org のテスト用マシン である bento.freebsd.org を使えばよいでしょう。 この場合、例えば以下のように設定します。

    mkdir ~/ports             # ~/ports/japanese/mh のように、 ~/ports 以下に
                              # テストする ports を展開する。
    mkdir ~/ports/distfiles   # ~/ports/distfiles にテストする ports の
                              # distfile を置く。
    setenv PORTSDIR ~/ports

日本の有志で運営されている monster.jp.freebsd.org もあります。 -current での ports 開発を行う方はこちらのアカウントを 申請するのも一手でしょう。

5.3. CVS でのファイル更新のしかた

まずは一般的なファイル更新について説明します。 新しい port を登録する場合は 次節 をご覧ください。 最初の commitremote CVS の節は読んでいない方は、まず そちらをご覧ください。

ports, doc, www 関係では CVS でそれほど複雑な技を使うことはありません。 cvs のコマンドのうち checkout (co), update, commit, diff, add, remove, history, log, status が使えれば十分でしょう。 import は通常 easy-import というスクリプトで行います。これについては 次節 で説明します。

port の変更を行う際は以下のような流れで行います。

  1. cvs checkout <NAME>
    すべての ports には CVSROOT/modules で module 名が定義されています。その module 名を <NAME> に指定します。 module 名を指定する代わりに
    cvs checkout ports/japanese/mh
    のように目的の port のパス名を直接指定することも可能です。
  2. cd <NAME>
  3. 変更作業 : edit, add, delete, etc.
  4. cvs add <追加したファイル>
  5. cvs remove <削除されたファイル>
    4, 5 はファイルのあるディレクトリで行います。例えば files/setup.tmpl を追加するなら、
    cd files; cvs add setup.tmpl
    とします。
  6. cvs update
    必要はありませんが、変更 / 追加 / 削除したファイルを教えてくれるので 便利です。また追加して cvs add し忘れたファイルは ? と 表示されます。
  7. cvs diff -u
    これも必須ではありませんが、確認のためです。
  8. cvs commit
    ここで commit log を入力します。簡単なメッセージなら
    cvs commit -m 'message'
    のように指定することもできます。
  9. cd ..; cvs rel -d <NAME>

doc, www の変更も ports の場合とほぼ同様です。

src 以下の場合、ソースにいくつかのブランチ (-current, -stable など) が あるのでそれに対応した作業が必要となります。 ここでは説明しませんので詳しくは CVS のマニュアルを参照してください。

5.4. 新しい port を登録するには

freefall にある easy-import というスクリプトで行います。 まず commit すべき port を展開してから easy-import を実行します。 次のような感じです。

freefall% easy-import
Import from which directory?
files   patches pkg     .
Which? [.]:                   # current directory を指定します。
Available repositories:
distrib doc     ports   src     www     
Enter repository (=complete, ^D=show): ports
                              # import する先を指定します。
                              # この場合は当然ながら ports です。
Selected repository: ports
Existent areas in this repository:
archivers astro      audio    benchmarks biology      cad       chinese  comms      converters
databases deskutils  devel    editors    emulators    games     german   graphics   japanese
korean    lang       mail     math       mbone        misc      net      news       plan9
print     russian    security shells     sysutils     templates textproc vietnamese www
x11       x11-clocks x11-fm   x11-fonts  x11-toolkits x11-wm       
Enter area name (=complete, ^D=show): emulators
                              # ports のカテゴリを入力します。
[Working on: ports/emulators]
Gimme the module name: xsystem35
                              # モジュール名を登録します。
Enter the module path: ports/emulators/xsystem35
                              # モジュールを置く path を指定します。
You're going to create the following new directories:
ports/emulators/xsystem35 
Enter a `vendor' tag (e. g. the authors ID): FLATHILL
                              # vendor tag を入力します。
Enter a `release' tag (e. g. the version #): v3_5_19981024
                              # リリースタグを入力します。

                              # 最後に Enter を押すとエディタが起動します。
                              # commit log を入力し終了すると commit されます。

easy-import で入力した内容について、順番に解説していきます。

ports のカテゴリ
ports 一覧 をみて 適当と思われるものを指定します。選択に迷う場合は freefall-committers ML などで質問してください。
モジュール名
通常は port の名前にします。日本語関係の japanese カテゴリなら ja-XXXX という名前にします。 CVSROOT/modules を調べて既存の port の module 名と 衝突しないように注意してください。
モジュールを置く path
ports のソースツリーでここで入力する path にソースが置かれます。
vendor tag
ports の場合、 port の作者 (submitter) の名前とすることが多いようです。 submitter が motoyuki@st.rim.or.jp なら MOTOYUKI とすればよいでしょう。 vendor tag は大文字で入力する必要があります。
release tag
ports の場合、 port のバージョンを書くことが多いようです。 例えば XMulti 2.00beta4 の port なら v2_00_beta4 とします。

5.5. PR を close する

send-pr されたものを commit した場合、 PR を close する必要があります。 この作業は freefall 上で行います。手順は以下の通りです。

  1. PR 番号を確認する。この例では ports/1111 では close する。
  2. edit-pr ports/1111 で edit-pr を起動する。
  3. エディタが起動するので State を open から closed に 変更し、保存して終了する。
  4. 続いてコメントを求められるので Committed. Thanks! などと入力する。

これの応用技として、自分がじっくり対処したい PR の責任者を自分に変更する ということもできます。 edit-pr コマンドで Responsible の項を自分の ログイン名に変更すれば OK です。こうしておけば、自分が作業中に他の committer に先を越される危険性がなくなります :-)

5.6. その他の作業

ports の commit をした場合、その port の作者を FreeBSD ハンドブックの Additional FreeBSD Contributors 一覧に追加する必要があります。 これは doc/handbook/submitters.sgml の 700 行目以降あたりにあります。


6. 細かな注意点

  1. 同じソフトウェアの違ったバージョンを port に登録する場合

    Repository copy などの方法を取ることがあるので import する前に *必ず* 浅見さん に相談してください。 GhostScript 関係の gs3, gs5 のように 少しでも似たものがあれば必ず聞いてください。

  2. CVS リポジトリに問題が発生したら

    CVS 保守担当の Peter Wemm <peter@freebsd.org> に連絡してください。

  3. 間違ったカテゴリ (例: japanese でなく korean に) に新しい port を import してしまったら

    間違って登録されたものを cvs remove して、さらに CVSROOT/modules の中の記述も消してから、新たに import し直します。 cvs remove されて Attic に移動したものは定期的に CVS 保守担当者が消去します。

  4. commit log を入力するときの注意

    cvs-commiters をしばらく見れば、どういう感じで入力するかの コツが掴めてくるでしょう。PR:, Submitted by: などの記述は忘れずに。

    多数のファイルを同時に commit する際に、一度 commit log を 入力したのに続けてまた入力を求められることがあります。 こうした場合は、何も入力しなければ最初に入力したログがそのまま 使用されます。

  5. 一度に多くの変更を commit するとき

    一度に複数の ports に対して同じ変更を加えることがあります。 例えば、自分が committer になった時に自分が MAINTAINER をしている ports の MAINTAINER を変更する場合などです。

    こうした場合、cvs commit で複数のディレクトリ名を 指定することによって、複数の ports を一度に commit することが できます。同じ内容の commit メッセージがたくさん流れるのは 嫌がられるので、 2, 3 個以上の ports で同じ内容の変更をするときは 必ずこの方法を使ってください。

  6. commit log の入力を忘れてしまったら

    普通は commit mail に reply する形でフォローすれば良いでしょう。 クレジットを入れ忘れた場合など失礼に当たると思われるときは、 同じファイルに対して
    cvs ci -f
    として commit を行い、 Log: に

            This is a null commit to record information I forgot to put in
            previous commit log.
    

    とでも書けばよいでしょう。

  7. ports の patches/patch-XX について

    基本的にパッチ先のファイルと patch-XX ファイルは一対一で 対応させます。 一つの patch-XX ファイルで複数のファイルを変更するようなことは 避けてください。

    また、 patch-XX といったファイル名は勝手に変更しては いけません。 新しいパッチが過去のものを完全に置き換えるものであっても、同じファイル へのパッチであれば同じ patch-XX というファイル名を 使ってください。 各ファイルについて CVS に log が記録されているため、記録の連続性が 失われてしまいます。

  8. FreeBSD のバージョンチェックについて

    ports の script などで FreeBSD のバージョンチェックを行なう場合が あります。こうした場合には FreeBSD 3.X や 4.X であるかをチェック するのではなく、 3.X 以上であることをチェックするなどしてください。 例えば

            freebsd[34]*)
                foo bar baz
    	

    とするのではなく、

            freebsd[3-9]*)
                foo bar baz
    	

    としてください。これは、将来的に FreeBSD 5.X が出る際にいちいち ports を修正しなくても済むようにするためです。ちなみに FreeBSD 5.0-current への branch date は 2001 年に予定されている とのことです。

  9. 他の committer が MAINTAINER をしている port

    については、できるだけその committer に担当してもらうように してください。修正すべき点をみつけたら担当の committer に連絡して 「作業しておいて」と返事をもらった時だけ commit しておいたほうが 無難です。


$MK: committers.html,v 1.9 2002/12/25 04:56:05 motoyuki Exp $