POPFile の開発者向けの情報 (FAQ)

1. POPFile の開発者になるためにはどうすればよいのですか?

POPFile の開発に興味があるなら、正しいページを開いています。最初にしなければならないのは、このドキュメントを読み、理解することです。

そして、POPFile ページにある Bleeding Edge - Source Code にアクセスして、なんらかのソースコードを書くことや提案をすることに興味があることを書いたメッセージを投稿してください。(フォーラムでは) アイデアに対する率直な反応が得られるでしょう。このことはとても重要です。なぜなら、他の人が作業しているようなコーディングをすることで、あなたの時間を無駄にしないためです。また、私があなたのアイデアをよいものだと思うかどうかを確かめるのも、よいアイデアでしょう。そうしないと、(作っても) 拒否されるものをコーディングすることになってしまうかもしれません。しかし、ほとんどの場合、POPFile の他の開発者から激励や提案があるでしょう。また、私から “見せてほしい” という反応があるでしょう。

私がコードの基礎において特に重視しているのは、コード自体の品質だということに留意してください。これは、POPFile のコーディングスタイルや、POPFile のテストをどのように書けばよいのかを理解するために、充分に時間をかけることが必要だということです。テストされていないものや、コーディングスタイルにあっていない POPFile に対する変更は拒否されるでしょう。

また、POPFile License Agreement に署名する必要があります。下記を参照してください。

2. パッチを投稿するにはどうすればよいのですか?

まず、このドキュメントをすべて読んで、 diff3 (あるいはそれに似たプログラム) を使ってパッチを作成し、 新しいチケットを作成(英語) してください。パッチがコーディング標準 (coding standard) にあっていること、また、関連する単体テストを含んでいること(パッチがとてもとても単純な場合を除く)を確認してください。

パッチを投稿する前に、あなたのバージョンのコードに対して POPFile のテスト・スイートを実行して、他の部分に影響がないかを確認することをおすすめします。コーディング標準にあっていて、自分自身のテストを含み、POPFile のすべてのテスト・スイートをパスしたパッチを投稿することは、私の信頼を得、あなたのコードを SVN に登録し、いつかあなた自身が SVN へのアクセス権を得るための最善の方法です。

3. SVN の commit 権限を得るためにはどうすればよいのですか?

POPFile コアチーム(The POPFile Core Team)のメンバー(Brian、Joseph、Manni、Naoki)に連絡してください(訳注:英語で)。あなたが一貫してすばらしいパッチを提供してくれて、[Bleeding Edge - Source Code] フォーラムにほかの開発者たちと参加することにより、CVS へのアクセスができるようになるでしょう、下記のコーディングガイドに従って、よいテストを書き、さらには私が POPFile に変更を加えたい場合には私の指示に従ってください。

4. POPFile (プロジェクト) にはコーディングスタイル (についてのルール) がありますか?

はい、以下のルールがあります (POPFile のすべてのソースコードがこのコーディングスタイルにあっているわけではないことに注意してください・・・きれいにすべきところを見つけたら、してください!)。

POPFile にはコーディングスタイルがあります。これは、コードに一貫性があるように見え、他の人に読みやすく、また理解しやすくするためです。POPFile のコーディング標準は、あなたの好みのスタイルとは違うかもしれません。残念! 個々のスタイルは重要なものです。しかし、複数のデベロッパの間でひとつの一貫したスタイルを使用することは、コードをきれいなまま保つために欠かせないことなのです。

— 混乱した Perl スクリプトにしないでください。Perl はクロスプラットフォームのコードを書く上で素晴らしい言語ですが、(気をつけないと) 簡単に弁解の余地のないあいまいなコードになってしまいます。ですから、できるだけ暗黙の変数を使わないようにして、新米の Perl プログラマがあなたの書いたコードを解読しようとしているのを想像しながらコーディングしてください。

— TAB 文字をファイルに含めず、インデントには 4 文字のスペースを使用してください。また、復帰コード(キャリッジリターン : CR)をファイルに含めないでください(訳注:すなわち、改行コードには行送りコード(ラインフィード : LF)のみを使用するということです)。

— { (中括弧)はサブルーチンの定義(sub)のあとでは次の行に書きますが、それ以外の場合はすべて行の最後に書きます。

sub foo
{
}

if ( $done != 0 ) {
}

— コメントブロックの上下は空行にします。短いコメントの場合も同様です。

  - Check whether the elephant feeding module is loaded and load it
  - if necessary

if ( $efm->loaded() ) {

— すべてのモジュール/ファイルには、以下のような、コードの名前と目的、標準的な著作権についての注意事項を書いたヘッダをつけなければいけません:

  ----------------------------------------------------------------------------
  -
  - Module.pm --- A module that handles the loading of banana wumpus drivers
  -               and links them into the octopus subsystem using dinolinking
  -
  - Copyright (c) 2001-2003 John Graham-Cumming
  -
  ----------------------------------------------------------------------------

— すべてのサブルーチンには以下のような形のヘッダをつけなければいけません:

  ----------------------------------------------------------------------------
  -
  - update_word
  -
  - Updates the word frequency for a word
  -
  - $word         The word that is being updated
  - $encoded      1 if the line was found in encoded text (base64)
  - $before       The character that appeared before the word in the original
  -               line
  - $after        The character that appeared after the word in the original
  -               line
  - $prefix       A string to prefix any words with in the corpus, used for
  -               the special identification of values found in for example
  -               the subject line
  -
  ----------------------------------------------------------------------------

— コメントがないと作用が明確でないコードには注釈をつけてください。 明確でないという基準はとても低いのですが、こんなふうには決して書かないでください:

  - Increment i ( i を 1 増加させる)

$i += 1;

このようなコメントがよいコメントです:

  - This is the A PIECE OF PLATFORM SPECIFIC CODE and all it does is force
  - Windows users to have v5.8.0 because that's the version with good fork()
  - support everyone else can use whatever they want.  This is probably only
  - temporary because at some point I am going to force 5.8.0 for everyone
  - because of the better Unicode support

my $on_windows = 0;

if ( $^O eq 'MSWin32' ) {
   require v5.8.0;
   $on_windows = 1;
}

— 優先順位に頼るのではなく、(丸)括弧を使ってください。

if ( ( $foo == $bar ) && ( $number > 0 ) ) {

と書いてください。以下のようにではなく:

if ( $foo == $bar && $number > 0 ) {

— elsif を使わないでください。POPFile の保証範囲のツールのコードに不都合が生じるからです。

— サブルーチンや変数の名前は小文字を使い、単語の間をアンダースコアでつなげてください。例えば、

start_your_engines();

といったように。

(訳注:コメントについては英語で書いていただくことになりますので、コメント部分はあえて翻訳していません)

5. POPFile はどのようにテストされていますか?

POPFile には、自動的にテストを行うための テスト・スイート があります。これは、tests.pl というスクリプトを使って実行されます。engine ディレクトリで make test と入力することにより、テストを実行することができますし、あるいは、単に tests.pl を自分で実行してもよいでしょう。

tests.pl は tests/ サブディレクトリを検索して、.tst で終わるファイルを探します。そして、それらを Perl スクリプトとして読み込みます。それぞれの .tst モジュールは test_assert( $test ) と test_assert_equal( $test, $expected ) という 2 つのヘルパー関数を使用します。test_assert はある特定のテスト (test_assert サブルーチンが評価 (計算) する任意の Perl コード) の結果が真 (true) であるかどうかを調べるために使われ、test_assert_equal は、あるテスト (test_assert_equal は $test パラメータについては評価しない) の結果が、ある想定された値と等しいかどうかを調べるために文字列や数値の比較をおこなう、すばらしいサブルーチンです。

tests.pl はすべての .tst ファイルを実行します。それぞれのテストがそれぞれのチェックを通過したテストごとに . を表示し、失敗した場合には適切なエラーを表示し、最後にはテストの合計数と失敗したテストの数についての概要を表示します。

POPFile に含まれるそれぞれの Perl モジュールには、tests/ サブディレクトリにそれぞれに対応するテストファイルがあります。例えば、MailParse.pm (というモジュール) には、TestMailParse.tst (というテスト) があります。

新しいコードを (CVS に) チェックインする前、あるいはパッチを投稿する前に、テスト・スイートを実行して、リグレッション (訳注:新しいコードを追加したことによって他の部分に悪影響を及ぼすこと) がないこと確認してください

6. なぜ 許諾契約書 (License Agreement) に署名して著作権を John Graham-Cumming に渡さないといけないのですか?

POPFile は フリーソフトウェアでよく使われている General Public License (GPL) に基づいて公開されていますが、実際のコードが GPL とは利害関係が異なる人からのクレームを受けないことを確実にするため、もし誰かが GPL を破った場合に私がちゃんと法定で争うことができるように、また、貢献者が提供したコードを使って POPFile の派生バージョンを法的な問題なく作成することができるようにするために、POPFile の貢献者 (パッチなどを提供する人) は、 POPFile License Agreement (許諾契約書) に署名することが求められます。

この契約書を簡単に要約すると、”あなたは私に、あなたが書いたコードが他の誰のものでもなく、あなたは私にそのコードを POPFile の中で自由に使える権利を与えることを告げ、私は POPFile で使われているあなたのコードが誰かに '損害を与えた' 場合にあなたが訴えられないように守ります。” という内容です。

コピーライトとコピーレフト、それから POPFile License Agreement についての背景の解説は以下で読むことができます (すべて英語です):

1. 私が POPFile とコードの著作権について書いたもとのスレッド

  https://sourceforge.net/forum/forum.php?thread_id=800798&forum_id=230652

2. Free Software Foundation の GPL についての FAQ

  http://www.fsf.org/licenses/gpl-faq.html
  
  重要なセクションはここです:
  http://www.fsf.org/licenses/gpl-faq.html#WhoHasThePower
  
  "Who has the power to enforce the GPL?
   
   Since the GPL is a copyright license, the copyright holders of the 
   software are the ones who have the power to enforce the GPL. If you see a 
   violation of the GPL, you should inform the developers of the GPL-covered
   software involved. They either are the copyright holders, or are connected
   with the copyright holders."

(参考) GNU GPLに関して良く聞かれる質問 (上記の日本語訳)

  http://www.fsf.org/licenses/gpl-faq.ja.html
  
  重要なセクションはここです:
  http://www.fsf.org/licenses/gpl-faq.ja.html#WhoHasThePower
  
  "GPLを強制する権力があるのは誰ですか?
   
   GPLは著作権に基づくライセンスですから、GPLを強制する権力を持つのは
   ソフトウェアの著作権者です。GPLに違反した事例を発見した場合、
   あなたは関係するGPLが保護されたソフトウェアの開発者たちに知らせる
   べきです。彼らは自身著作権者であるか、著作権者とつながりがあるかのどちらか
   でしょうから。"

私が POPFile の著作権についての明確な所有権を持っていることは不可欠です。 それは、GPL に基づいて訴える必要が生じたときに、私が障害なくそれを行うために 必要となるからです。

上記の FAQ をすべて読んでいただくよう、要望します。

3. Free Software Foundation の著作権譲渡についての注意書き

  http://www.fsf.org/licenses/why-assign.html
  
  "By Professor Eben Moglen, Columbia University Law School 
   
   Under US copyright law, which is the law under which most free software 
   programs have historically been first published, there are very 
   substantial procedural advantages to registration of copyright. And 
   despite the broad right of distribution conveyed by the GPL, enforcement 
   of copyright is generally not possible for distributors: only the 
   copyright holder or someone having assignment of the copyright can enforce 
   the license. If there are multiple authors of a copyrighted work, 
   successful enforcement depends on having the cooperation of all authors. 
   
   In order to make sure that all of our copyrights can meet the 
   recordkeeping and other requirements of registration, and in order to be 
   able to enforce the GPL most effectively, FSF requires that each author of 
   code incorporated in FSF projects provide a copyright assignment, and, 
   where appropriate, a disclaimer of any work-for-hire ownership claims by 
   the programmer's employer. That way we can be sure that all the code in FSF 
   projects is free code, whose freedom we can most effectively protect, and 
   therefore on which other developers can completely rely." 

(参考) なぜFSFは貢献者に著作権の譲渡をお願いしているのか (上記の日本語訳)

  http://www.fsf.org/licenses/why-assign.ja.html
  
  "Eben Moglen(Columbia大学ロースクール教授)著 
   
   歴史上ほとんどのフリーソフトウェア・プログラムはアメリカ合衆国の法の下で
   最初に発表されてきましたが、アメリカ法の下では著作権を登録することに手続き
   上非常に重要な利点があります。GPLによって伝達される幅広い頒布権にも関わら
   ず、著作権の行使は一般的に頒布者には不可能で、著作権者か著作権を上とされて
   いる誰かのみが権利を行使することができます。著作権が主張される著作物に複数
   の作者がいた場合、著作権の行使が成功するかどうかは作者全員が協力できるかに
   かかっています。 
   
   私たちのすべての著作権が登録の記録やその他必要条件と適合することを保証し、
   GPLの権利を最も効果的に行使できるようにするために、FSFはFSFのプロジェクトに
   統合されるコードを書いたそれぞれの作者に対して著作権の譲渡をお願いし、必要
   な場合には雇用上そのプログラマの雇用主に生じたあらゆる所有権の主張が放棄さ
   れているという声明文(disclaimer)を提供して頂くことにしています。これにより、
   私たちはFSFのプロジェクトのコードすべてが、私たちがその自由を最も効果的に
   保護でき、それによって他の開発者も完全に信頼することができることができる
   フリーなコードであることを保証できるのです。"

(訳注:上記日本語訳の中で、「著作権者か著作権を上とされている誰か」という表現がありますが、ここはおそらく「著作権者か著作権を譲渡されている誰か」の変換ミスだと思われます)

(訳注:ライセンス関係の文書は、英語で書かれた原文のみが法的な効力を持ち、日本語などの他の言語に翻訳されたものは、あくまで参考にしかなりません。このため、POPFile License Agreement については、日本語訳を作成していません)

POPFile License Agreement の書き方

以下は、amatubu の経験に基づき、POPFile License Agreement の書き方について書いたものです。

  • CONTRIBUTION DESCRIPTION 欄には、あなたの貢献の内容(例えば、作成したソースコードの概要)を記入します。
  • LICENSEE'S SIGNATURE 欄に、署名を行います(もちろん、内容を読んで、同意する場合)。電子メールで送信する場合は、最後に書かれているように /your name/ と、ローマ字小文字で書きます。例えば、私の場合であれば、/naoki iimura/ とします。
  • Date 欄には、署名した日付を記入します。January 20, 2005 など。
  • Name 欄には、名前を記入します。紙で送る場合には、ここはブロック体で記載してください。電子メールの場合は普通に記入します。
  • E-mail address 欄には、メールアドレスを記入します。

これで完成です。署名した License Agreement を電子メールで送付します。

原文

開発者向けコーナー

POPFile ドキュメンテーションプロジェクト

 
jp/developersguide.txt · Last modified: 2008/08/01 05:56 by amatubu

Should you find anything in the documentation that is incomplete, unclear, outdated or just plain wrong, please let us know and leave a note in the Documentation Forum.

Recent changes RSS feed Donate Driven by DokuWiki
The content of this wiki is protected by the GNU Fee Documentation License