null+****@clear*****
null+****@clear*****
2010年 9月 15日 (水) 11:32:46 JST
Kouhei Sutou 2010-09-15 02:32:46 +0000 (Wed, 15 Sep 2010)
New Revision: 4559286f74c62d083255ea29f3c2eb6eef2c42ff
Log:
add command_version document.
Added files:
doc/ja/source/command_version.txt
Modified files:
doc/ja/Makefile.am
doc/ja/source/commands.txt
doc/ja/source/http.txt
Modified: doc/ja/Makefile.am (+3 -0)
===================================================================
--- doc/ja/Makefile.am 2010-09-15 02:15:03 +0000 (c80a0c7)
+++ doc/ja/Makefile.am 2010-09-15 02:32:46 +0000 (e492609)
@@ -140,6 +140,7 @@ nobase_dist_doc_ja_DATA = \
source_files = \
source/__init__.py \
source/characteristic.txt \
+ source/command_version.txt \
source/commands.txt \
source/commands/cache_limit.txt \
source/commands/check.txt \
@@ -265,6 +266,7 @@ source_files = \
html_files = \
html/.buildinfo \
html/_sources/characteristic.txt \
+ html/_sources/command_version.txt \
html/_sources/commands.txt \
html/_sources/commands/cache_limit.txt \
html/_sources/commands/check.txt \
@@ -339,6 +341,7 @@ html_files = \
html/_static/sidebar.js \
html/_static/underscore.js \
html/characteristic.html \
+ html/command_version.html \
html/commands.html \
html/commands/cache_limit.html \
html/commands/check.html \
Added: doc/ja/source/command_version.txt (+75 -0) 100644
===================================================================
--- /dev/null
+++ doc/ja/source/command_version.txt 2010-09-15 02:32:46 +0000 (471d27e)
@@ -0,0 +1,75 @@
+.. highlightlang:: none
+
+.. _command_version:
+
+コマンドバージョン
+==================
+
+概要
+----
+
+groonga1.1からコマンドバージョンという概念が導入されます。コマンドバージョンは、selectやloadなどのgroongaのコマンドの仕様の互換性を表します。groongaパッケージのバージョンが新しくなったとしても、同一のコマンドバージョンが使用可能であるなら、すべてのコマンドについて互換性が保証されます。コマンドバージョンが異なれば、同じ名前のコマンドであっても、動作に互換性がない可能性があります。
+
+あるバージョンのgroongaは、二つのコマンドバージョンを同時にサポートするようになります。
+使用するコマンドバージョンは、groongaを起動する際のコマンドラインオプションないしコンフィグファイルにdefault-commnad-versionパラメータを与えることによって指定できます。また、個々のコマンドを実行する際に、command_versionパラメータを与えることによっても指定することができます。
+
+コマンドバージョンは1からはじまり、更新されるたびに1ずつ大きくなります。現状のgroongaのコマンドの仕様はcommand-version 1という扱いになります。次回提供するgroongaは、command-version 1とcommand-version 2の二つをサポートすることになります。
+
+バージョンの位置づけ
+--------------------
+
+あるバージョンのgroongaにおいてサポートされるコマンドバージョンは、develop, stable,deprecatedのいずれかの位置づけとなります。
+
+develop
+ まだ開発中であり、仕様が変更される可能性があります。
+
+stable
+ 使用可能であり仕様も安定しています。その時点で使用することが推奨されます。
+
+deprecated
+ 使用可能であり仕様も安定していますが、廃止予定であり使用が推奨されません。
+
+あるバージョンのgroongaがサポートする二つのコマンドバージョンのうち、いずれか一つが必ずstableの位置づけとなります。残りの一つは、developないしdeprecatedとなります。
+
+たとえば下記のようにgroongaのサポートするコマンドバージョンは推移します。::
+
+ groonga1.1: command-version1=stable command-version2=develop
+ groonga1.2: command-version1=deprecated command-version2=stable
+ groonga1.3: command-version2=stable command-version3=develop
+ groonga1.4: command-version2=deprecated command-version3=stable
+ groonga1.5: command-version3=stable command-version4=develop
+
+あるコマンドバージョンははじめにdevelop扱いとしてリリースされ、やがてstableに移行します。
+その後二世代経過するとそのコマンドバージョンはdeprecated扱いとなります。さらに次のコマンドバージョンがリリースされると、deprecatedだったコマンドバージョンはサポート対象外となります。
+
+default-commnad-versionパラメータやcommand_versionパラメータを指定せずにgroongaコマンドを実行した際には、その時点でstableであるコマンドバージョンが指定されたものとみなします。
+
+groongaプロセス起動時に、default-command-versionパラメータにstable扱いでないコマンドバージョンを指定した場合には、警告メッセージがログファイルに出力されます。また、サポート範囲外のコマンドバージョンを指定した場合にはエラーとなり、プロセスは速やかに停止します。
+
+コマンドバージョンの指定方法
+----------------------------
+
+コマンドバージョンの指定方法はgroonga実行モジュールの引数として指定する方法と各コマンドの引数として指定する方法があります。
+
+default-command-versionパラメータ
++++++++++++++++++++++++++++++++++
+
+groonga実行モジュールの引数としてdefault-command-versionパラメータを指定できます。
+(configファイルの中に指定することも可能です)
+
+実行例::
+
+ groonga --default-command-version 1
+
+そのプロセスで実行するすべてのコマンドについて、デフォルトのコマンドバージョンとして指定されたバージョンを使用します。指定されたコマンドバージョンがstableであった場合にはなんのメッセージも表示されずそのまま起動します。指定されたコマンドバージョンがdevelopあるいはdeprecatedであった場合には、groonga.logファイルに警告メッセージを出力します。指定されたコマンドバージョンがサポート対象外であった場合には標準エラー出力にエラーメッセージを出力し、プロセスは速やかに終了します。
+
+command_versionパラメータ
++++++++++++++++++++++++++
+
+select,loadなどのすべてのgroongaコマンドにcommand_versionが指定できます。
+
+実行例::
+
+ select --command_version 1 --table tablename
+
+指定されたコマンドバージョンでコマンドを実行します。指定されたコマンドバージョンがサポート対象外であった場合にはエラーが返されます。command-versionが指定されなかった場合は、当該プロセス起動時にdefault-command-versionに指定した値が指定されたものとみなします。
Modified: doc/ja/source/commands.txt (+5 -2)
===================================================================
--- doc/ja/source/commands.txt 2010-09-15 02:15:03 +0000 (0b604ca)
+++ doc/ja/source/commands.txt 2010-09-15 02:32:46 +0000 (c35f223)
@@ -1,10 +1,13 @@
.. highlightlang:: none
-組み込みコマンド一覧
-====================
+コマンド
+========
+
+まず、すべてのコマンドに関係するコマンドバージョンについて説明します。その後、組み込みのコマンドを順に説明します。
.. toctree::
:maxdepth: 1
:glob:
+ command_version
commands/*
Modified: doc/ja/source/http.txt (+3 -1)
===================================================================
--- doc/ja/source/http.txt 2010-09-15 02:15:03 +0000 (645726e)
+++ doc/ja/source/http.txt 2010-09-15 02:32:46 +0000 (a9cbf14)
@@ -26,7 +26,7 @@ groongaサーバを起動する時に--protocolオプションにhttpを指定
httpを指定して起動したgroongaサーバに対しても、他のモードで起動したgroongaと同じコマンドが使用できます。
-コマンドは、複数の引数をとります。引数にはそれぞれ名前があります。また、特殊な引数である「output_type」があります。
+コマンドは、複数の引数をとります。引数にはそれぞれ名前があります。また、特殊な引数である「output_type」と「command_version」があります。
スタンドアロンやクライアントモードでは、コマンドは以下のような形式で指定します。
@@ -46,6 +46,8 @@ GETメソッドのみが使用可能です。
output_typeにはjson, tsv, xmlが指定可能です。
+command_versionはコマンドの仕様の互換性を指定します。詳細は :ref:`command_version` を参照してください。
+
返値
----