目次
この文章について
この文書はロボット用OSであるROSの
wiki上にある開発者マニュアルを
日本語訳したものです。
ひと通り翻訳が終了したら、
ROSの日本語wikiにも転載しようと思います。
はじめに
ROSは大きなシステムであり、多くの人が多くのコードを書いています。
これらのコードを効率的に管理できるようにするために、
我々は下記の開発ガイドラインを作成しました。
是非、あなたのROS用コードも
下記のガイドラインに従うようにしてください。
1. ソースコードの管理
ROSはSubversion, Mercuria, Git, Bazaarなどの
ソースコード管理システムに対応しています。
また、現在ROSのコミュニティ内でも行われているように、
あなたのコードをGitHubやBitbucket, Google Codeなどの
ソース共有サイトで公開して共有することも大歓迎です。
ちなみにROSのメインコードはcode.ros.org, kforge.ros.orgで
公開されています。
ソースを共有する際に気をつけるべきことは下記の通りです。
・ソースコード管理システムにファイルを追加するときには、
あなたが書いたソースとパッケージを構成するための最低限の
ビルドファイルのみを追加してください。
オブジェクトファイル(.o)やライブラリファイル(.a,.sp.dll)
または自動的に生成された環境設定ファイルは追加しないでください。
svnは追加を行う時に、そのディレクトリの中身をすべて
再帰的に追加してしまいます。
なので、svnで追加をするときには、
かならずmake cleanを行ってから追加を行ってください。
大きなバイナリファイルを追加しないでください。
バイナリファイルは別webサーバにアップロードし、
あなたのビルドしたファイル内でそこからダウンロードするようにしてください。
・コミットは早めに頻繁に行ってください。
ソース管理システム内のすべては、一時的な書きなぐりコードの保管場所だと
思ってください。
複数の変更を一緒に一括でコミットするのではなく、
ある一つの変更をする毎にコミットするようにしてください。
そうしたほうが、プログラムのロールバックがしやすくなります。
・コミットしたら、参考になるメッセージを付記してコミットしてください。
・ビルドを壊さないでください。
コミットするまえに、あなたのコードが
ちゃんとコンパイルできるかどうかを確認してください。
２. バグトラッキング
我々は、バグレポートを含むそれぞれのパッケージや、
リクエスト対応、タスク割り当てなどのために、
複数のバグトラッカーを使用しています。
基本的には、それぞれのWikiのページ内から、
バグトラッキングシステムへのリンクを見つけることができるはずです。
GitHubにコミットされているパッケージに関しては、
そのリポジトリのissue trackerを使用します。
そして、そのパッケージの管理者はそれぞれの問題に関して、
マイルストーンを設定します。
このマイルストーンの設定によって、
バグの報告者はそのバグがいつ解決するのかを知ることができます。
これらのマイルストーンは一般的に、
新しいROSのリリース(GroovyやHydro)や
より細かいマイルストーン（Hydor beta版 1）が指定されます。
一方、そのバグや要求が将来的に修正されない/実装されない場合は、
マイルストーンは設定されません。
これは開発者のリソースによって決定されます。
またユーザにそのバグフィックスが
特定のリリースリポジトリで行われるかどうかを知らせるために、
管理者は、バグレポートをクローズしてリリースバージョンを指定するか、
すべてのリリースミラーに大してマイルストーンを指定する必要があります。
これにより、バグがフィックスされたリリースを使用できるかどうかを、
ユーザに知らせることができます。
もし、あなたがバグを見つけたら、チケットをオープンしてください。
同様に、何か欲しい機能があれば、チケットをオープンしてください。
Emailを送ることや、answers.ros.orgにポストすることや、
メーリングリストで主張することは、
問題を管理しにくくするので止めましょう。
もしチケットを発行してれば、ほとんど忘れ去られることはありません。
チケットを発行する際の注意点は下記の通りです。
1. チケット内にはできるだけ説明を多く記述しましょう。
・バグを再現させる方法を必ず記述しましょう。
・あなたのシステムや状態を必ず記述しましょう。
（何のパッケージのどのバージョンを使用しているのか？など）
２. チケットをオープンすることを恐れないようにしてください。
・多くの開発者が、バグの内容を忘れないように、
・自分自身でオープンしたチケットを自分自身にアサインしています。
もし、どのパッケージにバグが潜んでいるかや、
自分自身のシステムで既知のバグが生じているのかどうかが分からない時は、
まず初めに、answers.ros.orgで質問してください。
コードレイアウト
ROSのコードは複数のパッケージで構成されており、
それらのパッケージは1つのリポジトリにまとめることができます。
またそれらのパッケージは開発者がビルドをするコードの
単位ユニットとして扱われます。
特に、GitHubを使用している場合、
あなたのリポジトリ中をわかりやすくするために、
リポジトリのルートにREADME.mdファイルを作成しましょう。
加えて、このリポジトリに含まれているパッケージに関する
ROS wiki上のドキュメントへのリンクを
README.mdファイルの中に記述するようにしてください。
README.mdファイルの書き方に関しては、
この記事を参考にしてください。
パッケージング
ROSのパッケージやビルドシステムはmanifest.xmlで制御されます。
manifestに関しては下記の事項を守ってください。
・すべてのパッケージは、パッケージのトップディレクトリに
必ずmanifest.xmlを置いてください
・最低でもmanifestには下記の事項を記述してください。
1. 概要説明
2. 作者
3. ライセンス
下記はroscppを使用した場合のmanifestのテンプレートです。
LONGER DESCRIPTION
You/you@willowgarage.com
BSD
http://www.ros.org/wiki/YOURPACKAGE
加えて、下記はrospyを使用した場合のmanifestのテンプレートです。
LONGER DESCRIPTION
You/you@willowgarage.com
BSD
http://www.ros.org/wiki/YOURPACKAGE
GUIツールキット
現在ROSでは、
すべての新しいGUIの開発を
QtベースのGUIフレームワークであるrqtに移行しています。
fuerteより前に作成されたGUIシステムの多くはwxWidgetsを使用していましたが、
wxWidgetsはクロスプラットフォームの互換性があまり良くありませんでした。
したがって、もし新しいGUI開発を使用としている場合は、
rqtを使用することを検討してください。
開発の方法(Pythonで開発している時のライセンス問題も含む）は、
rqtのページに記述されています。
ビルド
基本的なビルドツールはCMakeです。
(参考資料：rosbuild - ROS Wiki）
CMakeによるビルドシステムの注意点は下記の通りです。
1．すべてのパッケージは、パッケージのトップディレクトリに
CMakeLists.txtを保有しており、これによりビルドステップが実施される。
2．今のところ、すべてのパッケージはMakefileも保有しており、
これによりビルドステップが実施されますが、
このMakefileの中身はできるだけ短くする必要があります。
3．ビルドを必要としないパッケージはCMakeLists.txtやMakefileなどの
ビルドファイルを持ってはいけません。
ライセンス
ROSはオープンソースのプロジェクトです。
(参考：The Open Source Initiative | Open Source Initiative)
我々は、大学院生から起業家まで、
広い範囲のユーザと開発者の手助けをしたいと思っています。
ライセンスに関しては、下記の事項に注意してください。
・我々はROSを商用利用されることを促進するために、
クローズドユースが可能な(Permissive) オープンソースライセンスを
使用することをお勧めします。
・ROSに関する推奨ライセンスはBSDライセンスです。
新しく作成されたコードに関しては
BSDライセンスを元に開発されるべきですし、
すべてのROSのコアコードはBSDライセンスです。
・コアノード以外に関しては、すべてのOSIが認証したライセンスが適応可能です。
OSIが認証したライセンスに関しては下記を参照してください。
Open Source Licenses | Open Source Initiative
・我々はROSの.msgファイルや.srvファイルには
著作権を付与しないライセンス(BSDなど)を付与することを強く薦めます。
なぜなら、このライセンスを使用することにより、
自動生成されるソースコードやデータ構造に関して、制限が無くなるからです。
・あるプロジェクトのライセンスに関するすべての条文は、
リポジトリの最上層にあるLICENSESディレクトリ内に置いてください。
もしLICENSESディレクトリ内に含まれない新しいライセンス条件下において、
新しいパッケージを追加した場合は、
LICENSESディレクトリにその新しいライセンスの条文を追加してください。
・すべてのソースコードには冒頭にライセンスの概要を記述してください。
またLICENSESフォルダには、
異なる言語によるライセンスの概要を記述してください。
また、再配布するサードパーティのコードに関する
ライセンスやコピーライトに関しては、
そのまま保持するものとします。
・我々は、使用しているサードパーティソフトのライセンス事項には
正確に従うものとします。例えば、
1.あるライブラリがGPLやLGPSのライセンスで、それをあなたが改変した場合、
あなたはその改変したコードをリリースする必要があります。
(GPL:GNU一般公衆ライセンス v3.0 - GNUプロジェクト)
(LGPS:GNU劣等一般公衆ライセンス v3.0 - GNUプロジェクト)
理想的には、あなたはそのライブラリの管理者にパッチを送った方がいいです。
または、改変したコードを誰もがアクセスできるリポジトリ
(例えばSourceForge)
に置くという方法でもOKです。
2．もし貴方がGPL'dライブラリを使用していた場合、
貴方が作成したパッケージはGPLライセンスである必要があります。
(GNU一般公衆ライセンス v3.0 - GNUプロジェクト)
また、GPLのライセンスと両立しないコードは使用することができません。
(さまざまなライセンスとそれらについての解説 - GNUプロジェク)
例えば、Creative Commons Attribution-Noncomeercial-Share
Alikeライセンスは、GPLと両立しません。
なぜならこのライセンスはGPSライセンスが
規定していない制限を課しているからです。
（例えば、このライセンスは帰属を要求していたり、
商用利用を禁止しています。）
・可能であれば、それぞれのROSのパッケージは
それぞれ1つのライセンスで管理されるべきです。
例えば、ROS CoreのようなBSDライセンスのコードは、
GPLラインセンスコードを使用しているパッケージに含まれることがあります。
この場合、GPLライセンスに準ずるために、
このBSDライセンスのコードは、
BSDとGPLの両方のライセンスで管理されるようになります。
これにより、このコードのユーザは
どちらのライセンスを使用するかを決定できるようになります。
しかし、これは大きな問題ではありません。
なぜならGPLライセンスは、単純にBSDに無い制限を加えているだけだからです。
・ROSのパッケージと通信システムは
複数のライセンスを繋げる役目を果たしています。
なぜなら、ノード同士がROSメッセージで通信した場合、
それぞれのノードのコードは互いにリンクしないからです。
つまり、パッケージによって、ライセンスの境界が作れるのです。
しかし、例外事項もあります。
もしあるパッケージがあるライブラリによって、
他のパッケージにリンクしていた時、
ライセンス条件は、それらのパッケージのライセンスを
組み合わせたものになります。
・こちらの記事も参考にしてください
著作権
国際的な著作権の条約であるベルヌ条約によれば、
ある作品の作者は、公式な著作権の文言の有る無しに関わらず、
著作権を有するとされています。
文学的及び美術的著作物の保護に関するベルヌ条約 - Wikipedia
しかし、著作権に関して明確にしておくことは、
長期間におけるプロジェクトの管理には重要なことです。
著作権に関しては、下記の事項に注意してください。
・それぞれのソースコードは、コードの冒頭に、
Copyright 2008 Jim Bob
のようにコピーライトのコメントを入れましょう。
この文言は、一般的にライセンスサマリの説明の
直前に記述されます。
・もし貴方が個人的にコードを作成していた場合、著作権は貴方が有します。
一方、もし貴方がWillow Garageのように
仕事としてソフトを作成していた場合は、
その著作権は雇用主が有するものとします。
デバック
下記のような、一般的なデバックツールはROS上でも使用できます。
1． GDB: The GNU Project Debugger
2． OProfile - A System Profiler for Linux (News)
3． Valgrind Home
これらのツールを使用してデバックを行うと時は、下記の内容を参考にして下さい。
もしあるfooというプログラムがクラッシュした場合、
GDBの中でプログラムを起動させてみてください。
下記のコマンドをコマンドラインで入力して、
GDB上でプログラムを動かします。
(gdb) run arg1 arg2 arg3
プログラムがクラッシュしたら, GDBのbtコマンドを使用して、
バックトレースを取得し、クラッシュ原因を解析することができます。
もしバグが、メモリ破損のような複雑なバグであった場合、
Valgrindを使用することをお勧めします。
まず、下記のコマンドを使用してvalgrind内でプログラムを動かします。
valgrind -v foo arg1 arg2 arg3
すると、Valgrindはすべてのメモリアクセスを解析するため、
クラッシュ原因を調べることができるはずです。
また、一般的にValgrindを使用すると、
これまで気が付かなかった別の問題を見つけることができます。
しかし、Valgridが警告を出した場合、
貴方のプログラムの実行速度が非常に遅くなる可能性があります。
ROS MasterやrospyのログはROS_ROOT/logに生成されます。
しかし、roscppのクライアントノードのログはデフォルトでは生成されません。
もし貴方が厄介なノードのデバックをしている時には、
2つのどちらかの方法でログを残すことができます。
まず一つ目は、コンストラクタの2つ目のパラメータの
WRITE_LOG_FILEに定数を与えること
(ANONYMOUS_NAMEのような他のオプションと同様です)
2つ目の方法は、
もし、ノードを再コンパイルしたくない時は、
コマンドラインのログのパラメータを下記のように設定すればOKです。
log:HOGEHOGE（HOGEHOGEは任意の定数です）
テスト
ROSの開発において、我々は2種類のレベルのテストを実施しています。
1． ライブラリ
ライブラリレベルにおいては、
我々は一般的なユニットテストのフレームワークを使用しています。
C++においては、gtest、Pythonにおいてはunittestを使用しています。
gtestの使い方に関してはこちら
ROS C++コード用テストライブラリgtestの使い方(日本語訳） - MY ENIGMA
2． メッセージ
メッセージレベルにおいては、
我々はrostestを使用してROSのノードを起動して、テストノードを起動し、
システムを分析しています。
また、テストの方法に関するガイドラインを作成しましたので、
こちらも参考にしてもらいたいと思います。
UnitTesting - ROS Wiki http://wiki.ros.org/UnitTesting
もし、あなたがソフトウェア開発をros, ros-pkg, wg-ros-pkgリポジトリ内で
行っている場合、自動ビルド＆テストシステムが稼働しているため、
ビルドと自動テストが様々なアーキテクチャ上で定期的に行われます。
もし、貴方のコミットの後にビルドやテストが完了できかなった場合、
エラーの内容とバグフィックスの要求がメールで自動的に連絡されます。
詳しい自動テストの内容に関しては下記の資料を参照してください。
AutomatedTesting - ROS Wiki http://wiki.ros.org/AutomatedTesting
文書化
すべてのコードは下記のQAProcessに従って文書化される必要があります。
QAProcess - ROS Wiki http://wiki.ros.org/QAProcess
ROS ソフトにおけるQAプロセス(日本語訳) - MY ENIGMA
簡単な概要としては、下記の2点に注意してください。
1．コードレベルのアクセス可能なAPI群に関しては、必ずドキュメント化すること
2．ROSレベルのアクセス可能なAPI群( Topic, Service, Parameter)に関しても、
必ずドキュメント化すること
ソフトウェアリリース
ROSのコミュニティに対するコードのリリースの方法に関しては、
下記のリリースのページを参照してください。
release - ROS Wiki http://wiki.ros.org/release
標準化
コードはROSの機能を出来るだけ使用し、そのガイドラインに従ってください。
・メッセージの出力に関しては、rosoutを使用してください。
rosout - ROS Wiki http://wiki.ros.org/rosout
・時刻制御ルーチンに関しては、ROSのClockを使用してください。
Clock - ROS Wiki http://wiki.ros.org/Clock
削除予告
貴方のコードにユーザがいる場合、
貴方は、急な変更によるシステム変更を防ぐ責任があります。
代わりに、開発者は削除予告プロセスを利用することができます。
これは、もうサポートしないコンポーネントや機能を指定し、
それらを削除するスケジュールを決めることができるプロセスです。
このようにユーザに機能削除に対する対応の時間を与えたあとで、
機能削除をすることが重要です。
削除予告は下記のような、複数のレベルが存在しています。
1． API機能
もしライブラリからあるメソッドを消去したい時には、
まず始めに、Doxgyenの@deprecatedコメントを使用して、
APIドキュメントに記述してください。
もし使用している言語がサポートしている場合は、
コードそのものにもdeprecated指定をしてください。
例えばC/C++では、 __attribute__ ( (deprecated) ) コマンドを使用してください。
そして、次のリリースでは、ChangeListに削除予告について記述し、
将来のリリースでは、この機能を削除する旨を伝えます。
また、この削除する機能が広くユーザに使用されている場合は、
削除予告の記述を目立つように書き、
なぜ、この機能を削除するのかを説明して下さい。
そして、予定のリリースが来たら、その機能を削除して下さい。
2. パッケージ
もし貴方があるパッケージを削除したい場合は、
Wikiの中に、そのパッケージを削除したい旨を記述して下さい。
( DPRECATEDと冒頭に記述して下さい)
また、いつそのパッケージを削除する予定なのかも記述してください。
また、次のスタックリリースのチェンジリストにも、
削除予定であることを記述してください。
もし、そのパッケージが多くのユーザに使用されている場合は、
ユーザにメールを送り、
できるだけ事前に警告をするようにしてください。
大きなデータ・テストファイル
1MBを超えるような大きなファイルは*-ros-pkgリポジトリには置かないで下さい。
特に、そのファイルがユニットテストの時のみ使用される場合は尚更です。
これらの大きなファイルは、誰かが貴方のパッケージをビルドするかにかかわらず、
リポジトリをチェックアウトする時に長い時間を必要としてしまいます。
このような大きなファイルはだれでもアクセス可能な
ウェブホスティングサイトに置くべきです。
また、必要なファイルはWebサーバ上に置くこともできます。
幾つかのファイルであれば、downloads.ros.orgに置くことも可能です。
必要な場合はros-release@code.ros.orgまで連絡してください。
もしビルドする際にそのような大きなファイルを必要とする場合は、
rosbuild_download_test_data(URL MD5SUM)
マクロを使用して下さい。
下記はこのマクロの使用例です。
rosbuild_download_test_data(http://code.ros.org/svn/data/robot_pose_ekf/zero_covariance.bag test/zero_covariance.bag 0a51b4f5001f446e8466bf7cc946fb86)
