ROS 2のパッケージを公開してみた

こんやっぴ〜、ForteFibreのインフラ担当マンゴーさんです！

今回は、parameter_expressionというちょっとしたROS 2のパッケージを実際にROSのレポジトリに公開してみたので、その記録を書いていこうと思います。

parameter_expressionについて

パラメータに文字列で数式を指定したときに、それをうまく解釈するためのパッケージです。

くわしく

ForteFibreでは、自律移動系からデバイスドライバまで多くの場所でROS 2を使っています。そして、ROSの特徴の一つであるパラメータファイルも大量に作成されます。
特に、デバイスドライバの周辺では、モータのギア比などを元に単位変換を行うノードが多く存在しています。
単位変換で用いるパラメータは、多くのユースケースに対応するために敢えて生の値を指定するのですが、パラメータファイルがYAMLで記述される都合上、計算後の値だけが指定されます。ちょうどこんな具合です。

ros__parameters:
  gain: 0.00002129448 # 2.0 * _pi / 8192.0 / 36.0

これでは直感的ではないということで、このパッケージを作成しました。これにより、現在では以下のような記法でパラメータが書かれています。

ros__parameters:
  gain: "2.0 * _pi / 8192.0 / 36.0"

詳細な使い方はGitHubのREADMEを確認してみてください。
https://github.com/ForteFibre/parameter_expression

ROS 2パッケージをROSのレポジトリに入れるまで

まずROSのレポジトリとは、簡単に言えばaptコマンドを使ってros-(distro)-*としてインストールされるパッケージ群が置かれている場所です。ROS Indexなどから一覧を見ることができます。
ここにパッケージを追加するには、いくつかのレポジトリを準備したり、Pull Requestを出したりする必要があります。
この記事では、その手法について書いていこうと思います。
内容としては、How-to Guides - Releasing a Packageと同様のものになります。

手順1. 公開したいパッケージを準備する

まず、公開するパッケージは基本的にソースコードが公開されている必要があります。また、ライセンスについても、OSI-approved licenseと指定されており、「オープンソース」であることが求められます。
そのライセンス情報を、package.xmlとLICENSEファイルの双方を用いて指定しておきます。
また、必須ではありませんが、今後レビュアーが読むことも考え、READMEを作成しておきます。

今回はROSパッケージでよく採用されるApache-2.0ライセンスを選びました。またREADMEとして、使用方法や依存関係、サンプル、Contribute Guideを載せたものを作成しました。

手順2. rosdistroにソースレポジトリの情報を加える

昔は必要なかったようですが、最近はrosdistroというレポジトリにPull Requestを出し、パッケージのソースレポジトリの情報を加える必要があります。rosdistroは、ROSのディストリビューションごとに使用できるパッケージ情報を格納しているもので、rosdepなどで参照されます。
また、パッケージレポジトリの構築のときの大元のデータにもなっているようです。

まず、rosdistroを手元にForkします。
そして、公開したいROSのディストリビューションを選びます。そして、(distro)/distribution.yamlのrepositoriesというキー以下に、以下のような内容を追記してください。

  parameter_expression:
    source:
      type: git
      url: https://github.com/ForteFibre/parameter_expression.git
      version: main
    status: developed

また、追加する場所は、キーがアルファベット順になるような場所でないといけません（このPRだと5861行目）。
しかし、その場所を手で探すのは面倒なので、rosdistro pip packageに同封されているrosdistro_reformatというツールを使います。
基本的には、rosdistroのレポジトリの直下で実行すれば、すべての変更したファイルについて、自動的に適切な位置に配置されます。

rosdistro_reformat index.yaml

ここまでくれば、あとは作成したForkからPull Requestを出します。
今回は以下のようなPull Requestになりました。
https://github.com/ros/rosdistro/pull/46912

Pull Requestの本文は、作成時に出てくるテンプレートのDOC_INDEX_TEMPLATEのものを使用します。
Sync（パッケージレポジトリの更新作業）があると、マージが遅れますが気長に待ちましょう。
また、これがマージされたあとSyncが行われると、ROS Indexに登録されるはずです。

手順3. リリースレポジトリを作成（依頼）する

ここでは、「リリースレポジトリ」と呼ばれるレポジトリを作成します。
このレポジトリには、後述するbloomというツールにより、リリースするパッケージのソースファイル群と各Linuxディストリビューション向けのビルドファイルが登録されます。
リリースレポジトリは、ros2-gbpというOrganizationに作成してもらう形を取ります。各自のパッケージを置いている場所（ユーザー・Organization）と同居させることもできますが、推奨されていません。

作成してもらう作業は、以下のレポジトリのIssueを通じて行います。
https://github.com/ros2-gbp/ros2-gbp-github-org/issues

（ユーザー・Organizationとして）初めてパッケージを公開する場合は、「New release team」からGitHubのユーザーを登録し、「New release repositories」からレポジトリを作成してもらいます。
今回は、既にRelease teamが存在したため、レポジトリの作成のみ行ってもらいました。

https://github.com/ros2-gbp/ros2-gbp-github-org/issues/826

このとき、先程のrosdistroへのPRがマージされている必要があるので注意してください。

手順4. バージョン作成とリリース

ここでは以下の2つのことを行います。

1. catkinによるpackage.xmlの更新
2. bloomによるリリースレポジトリの操作

手順4.0. bloomの準備

後で使用するbloomというツールでは、GitHubを操作するためのtokenを設定しないといけません。
GitHubから、Personal access tokenを作成します。
Fine-grainedなtokenで、以下のようなパーミッションを設定すれば十分でしょう（更に限定することも可能なはずですが、まだ試していません）。

後述するFork自動作成を行う場合、Repository Administrationのパーミッションも必要です

この作業は1回だけ行えば問題ないはずです。

手順4.1. catkinによるpackage.xmlの更新

package.xmlにある<version>タグを書き換え、バージョンを上げる・設定する作業です。
同時にCHANGELOGの自動生成も行います。

まず、CHANGELOGの生成を行います。以下のコマンドで、Gitの履歴に基づいたCHANGELOGが生成されます。

catkin_generate_changelog --all

生成されるCHANGELOGは、既存のCHANGELOG.rstにForthcomingというセクションが追加される形です。バージョンを上げるときに、ForthcomingがvX.X.Xのように変更されます。

続いて、バージョンを上げます。以下のコマンドで、バージョンとCHANGELOGの変更、tag打ち、tagのpushまでが行われます。

catkin_prepare_release

--bump minorや--bump major、--bump patchを与えることで付与されるバージョンが変わります

手順4.2. bloomによるリリース

ここまでの手順を行えば、あとはbloomというツールを使いパッケージの公開処理を行うだけです。
公開処理は大まかに2つのことを行います。

1. リリースレポジトリへのソースファイル等の公開
2. rosdistroにあるリリースレポジトリ情報の更新（Pull Request）

ここでは、新規にrollingのディストリビューションにリリースするためのコマンドを紹介します。

bloom-release --new-track --rosdistro rolling --track rolling parameter_expression

2回目以降はbloom-release --rosdistro rolling parameter_expressionのように短縮される

操作の最中、いくつか質問がされるのでそれに回答しないといけません。

• Release repository url: 作成してもらったリリースレポジトリのURL、例: https://github.com/ros2-gbp/parameter_expression-release.git
• Upstream Repository URI:: パッケージのレポジトリのURL、例: https://github.com/ForteFibre/parameter_expression.git
• Upstream Devel Branch:: パッケージのレポジトリのmain/masterブランチ（リリースしたいバージョンが入っている）の名前

また、途中でrosdistroのPR作成の処理が行われますが、ForkをOrganizationでしている場合は対応していなかったりするので、必要に応じて中断してください。
rosdistroをその場でForkすることも可能です（要パーミッション）。

リリース後は…

ここまでの作業後、Syncと呼ばれる定期的なパッケージ取り込み作業が行われると、apt等から公開したパッケージがインストールできるようになります。
おつかれさまでした！