[Back]

Software Release Practice HOWTO

Eric S. Raymond <esr@thyrsus.com>

1.2, 18 June 1999

福島於修 <fuku@amorph.rim.or.jp>

1.2j1, 30 June 1999


この HOWTO では Linux でのオープンソース・プロジェクトの公開にかかわる 望ましい慣例について解説します。 これらの慣例を踏襲することによって、 ユーザがソースコードからビルドして使用することが大変容易になりますし、 他の開発者はコードの内容を理解し、 改良に協力することができます。 この文書は開発の初心者にとっては必読のものです。 経験をつんだ開発者にとっても、 新しいプロジェクトをリリースする前に再確認すべき点を含んでいます。 この文書は、標準的な望ましい慣例の実情を反映して、 定期的に改訂する予定です。

1. はじめに

2. 正しいプロジェクトとアーカイヴの命名規則についての提案

3. 正しい開発作業についての提案

4. 正しい配布形態についての提案

5. 正しいコミュニケーションについての提案


1. はじめに

1.1 この文書が書かれた背景

オープンソースのコードをめぐっては、 誰かがそれを移植し、使用し、開発に協力することを妨げることのないよう、 数多くの伝統ある良き慣習が存在しています。 それらの慣例のいくつかは Unix および Linux の世界で 伝統的に受け継がれてきたものです。 その他の慣例は、 World Wide Web のような特徴ある新しい技術やツールに関連して、 最近になって生み出されたものです。

この文書は正しい慣習について知るための一助となるでしょう。 各章の見出しには、 それぞれがチェックリストの項目となるように要旨をまとめました。 あなたの配布物が旅に出る前の点検項目とお考え下さい。

1.2 この文書の最新の版

この文書は毎月 comp.os.linux.answers に投稿されます。 また metalab.unc.edupub/Linux/docs/HOWTO を含め、 数多くの Linux FTP サイトに保管されています。

また、この HOWTO の最新の版を World Wide Web では http://metalab.unc.edu/LDP/HOWTO/Software-Release-Practice-HOWTO.html で読むことができます。

この HOWTO に関する質問や意見は Eric S. Raymond, esr@snark.thyrsus.com 宛にお気軽にお寄せ下さい。

翻訳文に関して

この HOWTO の日本語版は http://www.linux.or.jp/JF/JFdocs/Software-Release-Practice-HOWTO.html で最新のものを読むことができます。 訳文に関する質問や意見は JF@linux.or.jp 宛にお寄せ下さい。

なお、翻訳文には JF Project の以下の方々の意見・校正が反映されています。


2. 正しいプロジェクトとアーカイヴの命名規則についての提案

Metalab や PSA そして CPAN のような アーカイヴサイトの管理者にかかる負担が増えるにつれて、 登録作業の一部あるいは全てをプログラムによって処理するという傾向に なってきています (つまり、人間によって行われるのではないということです)。

これによって プロジェクトとアーカイヴファイルの名称が、 計算機のプログラムによって解析し理解されるよう、 正しい形式で名前付けされていることの重要性が増しました。

2.1 基本名称 + major.minor.patch 番号という GNU スタイルを使いましょう

もし全てのアーカイヴのファイルに GNU のような名前付け -- つまり小文字のアルファベットから成る基本名称を頭に付けて、 ダッシュ (-) を付加し、続けてバージョン数字列、拡張子、 その他の識別子を付けるやり方 -- がされていたら、 これは誰の目にもわかりやすいものになります。

仮に `foobar' という名前で呼ばれているプロジェクトの、 バージョン 1、リリース 1、パッチレベル 3 があるとしましょう。 もしそれが単一のアーカイヴとして成立しているなら (おそらくは ソースコードでしょう)、以下のような名前付けがいいでしょう:

foobar-1.2.3.tar.gz

ソースアーカイヴ

foobar.lsm

LSM ファイル (Metalab に登録する場合).

次のようなのは ダメ です:

foobar123.tar.gz

これは多くのプログラムに `foobar123' という名の プロジェクトのバージョン番号のないアーカイヴと見なされてしまいます。

foobar1.2.3.tar.gz

これは多くのプログラムに `foobar1' という名の プロジェクトのバージョン 2.3 のアーカイヴと見なされてしまいます。

foobar-v1.2.3.tar.gz

多くのプログラムはこいつを `foobar-v1' という名のプロジェクトだと解釈されてしまいます。

foo_bar-1.2.3.tar.gz

アンダースコアは人間が喋りにくいし、 入力しづらいし、覚えにくいです。

FooBar-1.2.3.tar.gz

小賢しい利己主義者と思われても 構わない ならば。 おまけにこれは喋りにくいし、入力しづらいし、覚えにくいです。

ファイル名によってソースとバイナリアーカイヴや、 異なる種類のバイナリを区別したり、 ビルドの時のオプションのたぐいを表現する必要があるなら、 それらはバージョン番号の後に付加するファイル識別子として 取り扱うようにしてください。つまり、以下のような方法です:

foobar-1.2.3.src.tar.gz

ソースコード

foobar-1.2.3.bin.tar.gz

バイナリ (タイプは不明)

foobar-1.2.3.bin.ELF.tar.gz

ELF バイナリ

foobar-1.2.3.bin.ELF.static.tar.gz

静的にリンクされた ELF バイナリ

foobar-1.2.3.bin.SPARC.tar.gz

SPARC 向けバイナリ

`foobar-ELF-1.2.3.tar.gz' みたいなのはやめましょう。 これはプログラムが基本名称から内部識別子 (`-ELF' のような部分) を 導き出しにくくなるからです。

よい名前の一般的形式は、以下のような部分から順番に成り立っています:

  1. プロジェクトの基本名称
  2. ダッシュ (-)
  3. バージョン番号
  4. ドット (.)
  5. "src" または "bin" (任意)
  6. ドットまたはダッシュ (ドットが望ましい)
  7. バイナリタイプと付記事項 (任意)
  8. アーカイヴと圧縮手段の識別子

2.2 それでも「郷に入っては郷に従いましょう」

プロジェクトやコミュニティによっては、 名前付けとバージョン番号について明確に定義された慣習があり、 その場合は上記のアドバイスにならう必要はありません。 たとえば Apache のモジュールには mod_foo のような名前が一般的に使われており、 それ自身のバージョン番号とそれが動作する Apache のバージョン番号の両方が 付加されています。 同様に Perl のモジュールには浮動小数点として取り扱い可能なバージョン番号 が付けられていて (たとえば 1.3.3 のような形式よりも 1.303 のような形式を 見ることが多いでしょう)、Foo::Bar というモジュールのバージョン 1.303 の 配布物には、Foo-Bar-1.303.tar.gz という名称が付けられることが一般的です。

コミュニティと開発集団に独自の慣習を調べ、それを大切にしてください。

2.3 プロジェクトには特徴ある、入力しやすい基本名称を選びましょう

基本名称はプロジェクトのファイル全体を通して共通のものとし、 それは読みやすく、入力しやすく、そして覚えやすいものにするべきです。 アンダースコア(_)を使うのはやめましょう。 それと、格段の理由のない限り、 全体あるいは一部にでも大文字を使うのはやめましょう。 人間の目視による自然な検索順序を困惑させることになりますし、 まるで小賢しく立ち振舞おうとする下衆な利己主義者みたいじゃないですか。

ふたつの異なるプロジェクトが同じ基本名称を持つと、みんなが混乱します。 はじめてのリリースの前には名前が衝突してないかをチェックしましょう。 このチェックには index file of Metalab が便利です。


3. 正しい開発作業についての提案

ここで触れる話題のほとんどは、Linux 圏のみならず、 他の Unix も含めた移植性の確保に関係するものです。 他の Unix へ移植可能であるということは、 プロフェッショナリズムとハッカー主義の美徳であるだけでなく、 将来において Linux 自体に変化が起きた場合にそなえた 貴重な保険ということもできます。

結論から言えば、誰かがあなたのコードを Linux 以外のシステムにおいて ビルドしようとするのは明らかです。 移植性を高めておけば、あなたが受け取る煩わしくて面倒な email の数を 減らすことができるでしょう。

3.1 純粋な ANSI C もしくは可搬性の高いスクリプト言語を使いましょう

移植性と安定性のために、ANSI C もしくは可搬性の保証されているスクリプト言語を 使いましょう。 プラットフォームを越えて単一の実装が存在しているからです。

これに適合するスクリプト言語としては、 Python, Perl, Tcl, そして Emacs Lisp などがあります。 プレインな古い shell は不合格です。 微妙な違いのある、たくさんの異なる実装が存在していますし、 エイリアスのようなユーザカスタマイズによって、 shell の実行環境が ごちゃごちゃになっていることも想定されるからです。

Java は可搬性の高い言語であることを約束していますが、 今のところ Linux で利用できる実装は完全ではなく、 Linux との親和性も貧弱です。 Java は成熟するに連れてさらに人気を増していくように見えますが、 現時点ではまだ薄氷を踏むような選択と言えます。

3.2 正しい C 言語の互換性に留意しましょう

C 言語で開発しているなら、ANSI で用意されたすべての機能を 好きなように使ってください。モジュール間の矛盾を洗い出すために 便利なファンクション・プロトタイプもこれに含まれます。 旧式の K&R コンパイラはすでに歴史の遺物です。

その一方で、たとえば `-pipe' オプションやネストされた関数構造など、 GCC 固有の機能が使えると仮定してはいけません。 誰かが Linux 以外、GCC 以外のシステムに移植する際に、 この問題が付きまとい、困らせることになります。

3.3 autoconf/automake/autoheader を使いましょう

C 言語で開発しているなら、システムの環境設定を探査したり、 makefile を仕立てたりといった、可搬性にまつわる事柄を操作するために、 autoconf/automake/autoheader ユーティリティーを使いましょう。 今日では、ソースからビルドする際に、 "configure; make" とタイプして、きれいに -- 文字通り きれいに作り上げられることを人々は期待しているのです。

3.4 リリースの前にコードの正当性をチェックしましょう

C 言語で開発している場合は、 リリースの前に少なくとも一回は -Wall オプションを付けてテストコンパイルを行い、 エラーが出ないことを確認しましょう。 これは非常に多くのエラーを検出します。 究極を目指すなら、-pedantic オプションを付けてコンパイルしてみましょう。

Perl で書いている場合は、コードに -c (場合によっては -T) オプションを付けて チェックしてみましょう。信心深く行うなら perl -w と `use strict' ですね (これについては Perl のドキュメントを参照してください)。


4. 正しい配布形態についての提案

これから述べるガイドラインでは、誰かが配布物をダウンロードし、中身を取り出して 展開した際に、配布物はどのように現れるべきか、という事を説明します。

4.1 tarball からは常に単一の新しいディレクトリに展開されることを確認しましょう

開発の初心者が冒しやすい誤りの中で、もっともわずらわしいものは、 配布物中のファイルとディレクトリをカレントディレクトリにぶちまけ、 すでにそこにあるファイル群を上書きする可能性のある tarball を作ってしまう、というものです。 こうしては絶対にいけません!

これを避けるには、アーカイヴされたファイルを全てプロジェクト名で始まる 専用のディレクトリに入れれば、現在のディレクトリの直下 にある、単一のトップ・ディレクトリの中に展開されるでしょう。

これを完璧に行うための makefile の裏技があります。 配布物のディレクトリが `foobar' という名前で、 SRC という変数には配布ファイルのリストが入っているとします。 これには GNU tar 1.13 が必要です。

VERS=1.0
foobar-$(VERS).tar.gz:
        tar --name-prefix='foobar-$(VERS)/' -czf foobar-$(VERS).tar.gz $(SRC)

もし古い tar を使っている場合は、以下のようにします。

foobar-$(VERS).tar.gz:
        @ls $(SRC) | sed s:^:foobar-$(VERS)/: >MANIFEST
        @(cd ..; ln -s foobar foobar-$(VERS))
        (cd ..; tar -czvf foobar/foobar-$(VERS).tar.gz `cat foobar/MANIFEST`)
        @(cd ..; rm foobar-$(VERS))

4.2 README を用意しましょう

ソース配布物のロードマップとなる README もしくは READ.ME というファイルを 用意しましょう。古来の言い伝えでは、これはソースを展開した勇敢なる探検者たちが 最初に目にして読むはずの書、ということになっています。

README の中に書いておきたい項目は:

4.3 標準的なファイル命名規則を重んじてそれに従いましょう

README ファイルを読むより先に、 勇敢なる探検者たちは展開した 配布物のトップディレクトリのファイル名を探索するでしょう。 ファイルの名称は、それ自体が情報を含んでいます。 標準的な名前付けの慣例を踏襲することによって、 次に何を見るべきなのかという重要な手がかりを、探検者たちに示すことができます。

標準的なトップレベルのファイル名とそれが意味するものについて説明しましょう。 配布物にこれら全部が必要ではありません。

README または READ.ME

最初に読む案内書

INSTALL

設定・ビルド・インストール方法の解説

CREDITS

プロジェクトに対する貢献者のリスト

NEWS

プロジェクトに関する最近のニュース

HISTORY

プロジェクトの履歴

COPYING

プロジェクトのライセンス (GNU 流の慣習)

LICENSE

プロジェクトのライセンス

MANIFEST

配布物に含まれるファイルの一覧

FAQ

プロジェクトに関して、よく尋ねられる質問とその回答を記したプレインテキストのドキュメント

TAGS

Emacs や vi で利用するタグファイル

これらのファイル名が全て大文字で構成されているという慣習は、 それらがビルドの部品として使われるのではなく、 パッケージに関する一般的情報を含んだ人間が読むべきものだと 暗示していることに注意してください。


5. 正しいコミュニケーションについての提案

あなたのソフトウェアは、 その存在を知られない限り世界に貢献することはできません。 また、プロジェクトの存在をインターネット上で明らかにすることは、 ユーザを増やしたり共同開発者を募るのに役立つでしょう。 これについての標準的な手法に関して解説します。

5.1 c.o.l.a でアナウンスしましょう

comp.os.linux.announce で新たなリリースのお知らせをしましょう。

それ自体がよく購読されている Newsgroup である上に、 Freshmeat のような Web ベースで新着情報を扱うサイトへも転送されています。

5.2 関連する Newsgroup にアナウンスしましょう

あなたのアプリケーションに直接関連する USENET の Newsgroup を見つけて、 そこでもアナウンスしましょう。 慎みを持って、 ソフトウェアとしての機能が関係する Newsgroup にのみ投稿してください。

例えば IMAP サーバに問い合わせを行う Perl で書かれたプログラムを リリースしようとしているなら、 間違いなく comp.mail.imap には投稿するべきでしょう。 しかしプログラムが Perl の先鋭的テクニックのお手本にもなるものでなければ、 おそらく comp.lang.perl には投稿しない方がよいでしょう。

アナウンスにはプロジェクトの Web サイトの URL も示しておきましょう。

(訳注: 日本語の Newsgroup では fj.sources でソフトウェア公開のアナウンスがされています。 本来テキストエンコードされたソースコードのアーカイブを、 直接投稿する Newsgroup でしたが、 最近はアナウンスのみを投稿することの方が増えています。 投稿する記事には Followup-To: ヘッダで fj.sources.d を指定することがマナーとなっています。)

5.3 Web サイトを用意しましょう

プロジェクトのユーザあるいは開発者のコミュニティを しっかりと築くことを目指すならば、 Web サイトを用意した方がよいでしょう。 Web サイトに用意する標準的な内容は以下のようなものです:

プロジェクトのサイトによっては、 一次ソースツリーへの匿名アクセスが可能な URL を用意することもあります。

5.4 プロジェクトのメーリングリストを用意しましょう

開発の協力者が交流を行い、パッチを交換できるような非公開のメーリングリストを 用意することが一般によく行われています。 プロジェクトの進歩状況を知らせて欲しい人々を対象とした、アナウンスのための メーリングリストがあってもよいでしょう。

5.5 主要なアーカイブサイトに置きましょう

ここ数年の間、 Metalab archive は Linux のソフトウェアのための重要な拠点となってきました。

それ以外に以下のような重要なサイトがあります:

5.6 RPM バイナリパッケージを提供しましょう

インストールに使われるバイナリパッケージの事実上の標準フォーマットは、 Red Hat Package Manager, RPM です。 これはもっとも人気のある Linux ディストリビューションの特長となっており、 事実上 (Debian と Slackware を除いた) 他の Linux ディストリビューションでも サポートされています。

したがって、ソースコードの tarball と同様に、 インストール可能な RPM 形式のファイルを プロジェクトのサイトで提供するのも良い考えでしょう。


sgml21html conversion date: Sun Jul 18 00:27:51 JST 1999