注意: このドキュメントの内容はかなり古くなっています。 Resources for FreeBSD Committers などで最新の情報を確認してください。
これは FreeBSD.org の committer としての作業に関する非公式ガイドです。
このガイドは、 浅見さんを始めとする多くの FreeBSD 関係者とのやりとりから生まれたものです。 特に 佐田さん、 平岡さん の committer 作業に関する Web ページは非常に参考になりました。
committer になってしばらくすると、 Eivind Eklund <eivind@yes.no> からメールが届くことと思います。 このメールには committer として作業する上で必須の情報が書かれてるので、 必ず読んでおいてください。 筆者に届いたのは このようなメール でした。
このページでは、 Elvind からのメールだけでは不足しがちな、 committer として作業していくうえでのさまざまな情報を提供していきたいと 考えています。
まず最初に 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 作成用 マシンがありましたが、こちらは無くなりました。
ログインには普通の telnet も使えますが、セキュリティを 考えると ssh(1) の使用をお勧めします。 ssh は FreeBSD の ports/packages に 含まれています。
ssh でログインするには ssh HOSTNAME とします。
telnet と同じくログイン先での passwd が要求されます。
~/.ssh/identity.pub を ログイン先の
~/.ssh/authorized_keys にコピーする。
という手順で passphrase を用いた認証を行うようにしておくと良いでしょう。 ssh-agent(1) を利用すると passphrase 入力を自動化することもできます。 詳しくは ssh のマニュアルを参照してください。
FreeBSD.org のマシンでは ssh の X11 forwarding が有効になっているので、 ssh でログインした状態で xterm などの X のプログラムを起動すれば手元の X に画面が表示されます。
ssh については 佐田さんのページ に 解説 があります。 また UNIX マガジンの 1998 年 6 - 8 月号にも解説がありました。
メールの転送についてですが、 ~/.forward では設定できません。
hub.freebsd.org の /var/forward/USERNAME を編集してください。
commit 作業の関係上、 umask は 002 に設定しておいてください。 home directory は各ユーザのみが所属するグループになっていますので、 個人のファイルが他人に書き換えられる心配はありません。
その他の環境設定については普通の FreeBSD マシンと同じです。
~/public_html/ にファイルを置けば
http://www.freebsd.org/~USERNAME/ でアクセスすることができます。
簡単な自己紹介を置いておくことが推奨されているようです。
他のメンバーのホームページは
個人のページ一覧
で参照することができます。
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 経由での変更はできません。
commit 作業をする際の要です。最近だと UNIX マガジンの 1997 年 11 月号と 1998 年 1, 2 月号に解説があったので、バックナンバーが 手元にあれば参照するといいでしょう。 FreeBSD のソースコードの /usr/src/contrib/cvs/FAQ に英語版の FAQ があります。
CVS では一カ所にある CVS リポジトリ (書庫のようなものです) に ソースコード本体やそこに加えられた変更が全て記録されています。 FreeBSD では freefall.freebsd.org の /home/ncvs に CVS リポジトリが 置かれています。 CVS での作業は基本的に
という手順をとります。
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 までメールしていただければ幸いです。
CVS の変更を見るための Web インターフェースとして CVSweb があります。
後者はミラーなので多少更新が遅いです。
手元のマシンに余裕があれば、 CVSup を使って FreeBSD の CVS リ ポジトリ全体を手元のマシンに持ってきておくといいでしょう。 この手順については CVSup を使う を参照してください。技術評論社の「FreeBSD フルコース」の書籍版に非常 に詳しい解説があるので、手元にあれば参照するといいでしょう。
手元のマシンで httpd を走らせている場合は、ローカルで CVSweb を 走らせることもできます。 CVSweb のソースは www/en/cgi/ にあります。作業を進めるのに非常に便利ですので、是非お勧めします。
前節 では 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
としています。こうしておくと
のように freefall.freebsd.org へのアクセスを最低限に抑えて、 手元でほとんどの作業を行うことができます。
自分で作成したコードを 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 以下に移動してくれ、 と依頼してください。
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 開発を行う方はこちらのアカウントを 申請するのも一手でしょう。
まずは一般的なファイル更新について説明します。 新しい port を登録する場合は 次節 をご覧ください。 最初の commit と remote CVS の節は読んでいない方は、まず そちらをご覧ください。
ports, doc, www 関係では CVS でそれほど複雑な技を使うことはありません。 cvs のコマンドのうち checkout (co), update, commit, diff, add, remove, history, log, status が使えれば十分でしょう。 import は通常 easy-import というスクリプトで行います。これについては 次節 で説明します。
port の変更を行う際は以下のような流れで行います。
cvs checkout <NAME><NAME> に指定します。 module 名を指定する代わりにcvs checkout ports/japanese/mhcd <NAME>
変更作業 : edit, add, delete, etc.
cvs add <追加したファイル>
cvs remove <削除されたファイル>files/setup.tmpl を追加するなら、cd files; cvs add setup.tmplcvs updatecvs add し忘れたファイルは ? と
表示されます。
cvs diff -ucvs commitcvs commit -m 'message'cd ..; cvs rel -d <NAME>
doc, www の変更も ports の場合とほぼ同様です。
src 以下の場合、ソースにいくつかのブランチ (-current, -stable など) が あるのでそれに対応した作業が必要となります。 ここでは説明しませんので詳しくは CVS のマニュアルを参照してください。
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 で入力した内容について、順番に解説していきます。
send-pr されたものを commit した場合、 PR を close する必要があります。 この作業は freefall 上で行います。手順は以下の通りです。
edit-pr ports/1111 で edit-pr を起動する。
open から
closed に
変更し、保存して終了する。
Committed. Thanks!
などと入力する。
これの応用技として、自分がじっくり対処したい PR の責任者を自分に変更する ということもできます。 edit-pr コマンドで Responsible の項を自分の ログイン名に変更すれば OK です。こうしておけば、自分が作業中に他の committer に先を越される危険性がなくなります :-)
ports の commit をした場合、その port の作者を FreeBSD ハンドブックの Additional FreeBSD Contributors 一覧に追加する必要があります。 これは doc/handbook/submitters.sgml の 700 行目以降あたりにあります。
Repository copy などの方法を取ることがあるので import する前に ＊必ず＊ 浅見さん に相談してください。 GhostScript 関係の gs3, gs5 のように 少しでも似たものがあれば必ず聞いてください。
CVS 保守担当の Peter Wemm <peter@freebsd.org> に連絡してください。
間違って登録されたものを cvs remove して、さらに CVSROOT/modules の中の記述も消してから、新たに import し直します。 cvs remove されて Attic に移動したものは定期的に CVS 保守担当者が消去します。
cvs-commiters をしばらく見れば、どういう感じで入力するかの コツが掴めてくるでしょう。
PR:,Submitted by:などの記述は忘れずに。多数のファイルを同時に commit する際に、一度 commit log を 入力したのに続けてまた入力を求められることがあります。 こうした場合は、何も入力しなければ最初に入力したログがそのまま 使用されます。
一度に複数の ports に対して同じ変更を加えることがあります。 例えば、自分が committer になった時に自分が MAINTAINER をしている ports の MAINTAINER を変更する場合などです。
こうした場合、
cvs commitで複数のディレクトリ名を 指定することによって、複数の ports を一度に commit することが できます。同じ内容の commit メッセージがたくさん流れるのは 嫌がられるので、 2, 3 個以上の ports で同じ内容の変更をするときは 必ずこの方法を使ってください。
普通は commit mail に reply する形でフォローすれば良いでしょう。 クレジットを入れ忘れた場合など失礼に当たると思われるときは、 同じファイルに対して
cvs ci -f
として commit を行い、 Log: にThis is a null commit to record information I forgot to put in previous commit log.とでも書けばよいでしょう。
patches/patch-XX について
基本的にパッチ先のファイルと
patch-XXファイルは一対一で 対応させます。 一つのpatch-XXファイルで複数のファイルを変更するようなことは 避けてください。また、
patch-XXといったファイル名は勝手に変更しては いけません。 新しいパッチが過去のものを完全に置き換えるものであっても、同じファイル へのパッチであれば同じpatch-XXというファイル名を 使ってください。 各ファイルについて CVS に log が記録されているため、記録の連続性が 失われてしまいます。
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 年に予定されている とのことです。
については、できるだけその committer に担当してもらうように してください。修正すべき点をみつけたら担当の committer に連絡して 「作業しておいて」と返事をもらった時だけ commit しておいたほうが 無難です。
$MK: committers.html,v 1.9 2002/12/25 04:56:05 motoyuki Exp $