初めてのパッケージリリース

この文書は，"bloom"と"catkin"を使って，新しいROSパッケージをリリースするためのガイドです．bloomは通常，パブリックなROSビルドファームにパッケージをリリースしますが，そのやり方です．リリースされているパッケージやさらなる情報はhttp://build.ros.org を参照してください．

リリースの準備

1. bloomをインストールしましょう. パッケージをリリースするためのツールです．

2. ソースコードが最新で，すべてのテストを通過して，すべての変更が上流レポジトリにプッシュされていることを確認しましょう．上流レポジトリとは，あなたのパッケージのソースコードを管理し，開発に用いられているレポジトリです．上流レポジトリはgit, hg, svnといったVCS（ローカルなものでも可能です）や，アーカイブファイル(今はtar.gzのみですが，tar.bzやzipのサポートも計画されています）など，どこで管理されていてもOKです．Bloomがあなたのパッケージを扱うときに重要なことがあります．もしあなたの上流レポジトリがVCSなら，リリースするバージョン番号と同じタグが付いている必要があります．例えば，あなたのパッケージがバージョン0.1.0だった場合，bloomは上流レポジトリにタグ"0.1.0"が付くものとして扱います．この後のチュートリアルに従えば，このタグは自動的に付けられるので，自分で今タグを付ける必要はありません．もしバージョンのタグの付け方を独自の方法にしたい場合には，bloomはそれを"Release Tag"の設定を使ったリリース・トラックで扱うことができます．

3. Perform a pre-release test by following the pre-release instructionsにしたがって，プレ・リリーステストを行いましょう．このステップは必須ではありませんが，ぜひやっておくべきです．プレ・リリースにより，あなたのパッケージが別のマシン（実際はDockerコンテナ）で正しくビルドでき，テストを通過することを確認できます．プレ・リリーステストはあなたのリリースに問題があった時に，解決しやすくしてくれるはずです．

<string>:21: (ERROR/3) Unknown target name: "name".

* fix for checking the ``name_``

## Review, Edit and Commit your changes!
変更したら，レビューし，修正し，コミットしましょう！

リリースレポジトリの作成

次のステップは，リリースレポジトリを作成することです．Bloomはリリースのため，上流レポジトリとは別の"リリース"レポジトリを必要とします．リリースレポジトリはGitHubのような外部公開されたgitリポジトリである必要があります．例えば，すべてのROSのリリースレポジトリはros-gbp github organizationにあります．これらのレポジトリは一つもしくは複数のcatkinパッケージでbloomを実行した結果です．

リリースレポジトリにはGitHubを使うことを強くお勧めします．このチュートリアルではGitHubを使いますが，どこか他の場所で管理されたリリースレポジトリを使うこともできます（訳注：まあGitHub使っとけということでしょう)

GitHub上のリリースレポジトリの作成

GitHub上の組織もしくはユーザに，新しいレポジトリを作成します．慣習として，レポジトリの名前は，パッケージ名の後ろに-releaseをつけたものにすべきです．つまり，ros_commレポジトリに対応するリリースレポジトリはros_comm-releaseとなります．注意：GitHubでレポジトリを作成するときに，Initialize this repository with a README.mdのチェックボックスをオンにして，レポジトリを有効にしてください．Bloomは後でこのREADME.mdファイルの中にリリースのバージョン情報を書き加えます．

新しいリリースレポジトリを作ったら，あなたのパッケージを設定してリリースする準備が整いました．次のステップで用いるので，リリースレポジトリのURLをコピーしておきましょう．

パッケージのリリース

通常のリリースサイクルでは，このようにbloomを起動します：

• # This is an example, do not run this one, run the next one
  $ bloom-release --rosdistro <ros_distro> --track <ros_distro> repository_name

しかし，最初のリリースの場合（もしくは，あたらしいトラックの設定を行いたい場合）には，--editオプションを追加した方がいいでしょう．

• # Replace <ros_distro> with the ROS distribution, e.g. indigo
  $ bloom-release --rosdistro <ros_distro> --track <ros_distro> <your_repository_name> --edit

このオプションは，リリースする前に，指定されたトラックの情報を編集することができます．最初のリリースではまだトラックが存在しないので，それを作成して設定するためにこのオプションが必要です．repository_nameはURLではないことに注意してください．それはdistribution.yaml内で参照される名前です（訳注：GitHubのレポジトリ名で良いと思われる，なので，レポジトリ名=メタパッケージ名としたほうが分かりやすい）

上のコマンドを起動すると，指定したROSバージョンに対応するファイルが生成され，リリースレポジトリの情報を探します．最初のリリースでは，bloomはリリースレポジトリの情報をまったく知らないため，以下のようにそのURLを指定します：

No reasonable default release repository url could be determined from previous releases.
Release repository url [press enter to abort]:

リリースレポジトリ（先ほど作成した"パッケージ名-release"のリポジトリです）のURLを入力します．最初のリリースの際にのみ，入力が必要です．

つぎにbloomはレポジトリを新しく初期化するかを尋ねてきます．

Freshly initialized git repository detected.
An initial empty commit is going to be made.
Continue [Y/n]?

'y'もしくはそのままEnterで次に進みます．（訳注：通常，大文字で書かれた選択肢がデフォルトなのでEnterでそれが選択されます）

Bloomがmasterブランチを作成し，設定ファイル群が保管されます．次にリリースについての情報を尋ねてきます．

リリース・トラックの設定

Bloomは同じリリースレポジトリを使って，一つのパッケージを異なるROSディストリビューションとバージョンにリリース出来るように設計されています．その設定のため，bloomはそれぞれのリリース作業を"リリース・トラック"として管理します． 通常のcatkinを用いたROSパッケージは，デフォルトのリリース・トラックを用いることをお勧めします．

上で起動したbloom-releaseコマンドでは，--trackオプションでトラックの名前を指定しました．どのような名前でも構いませんが，慣習により，リリースの対象となるROSディストリビューションの名前(indigo, kinetic, lunarなど)を使うべきです．

最初の質問は上流レポジトリの名前です:

Repository Name:
  upstream
    Default value, leave this as upstream if you are unsure
  <name>
    Name of the repository (used in the archive name)
  ['upstream']:

この名前（訳注：upstreamがデフォルト値）はあまり重要ではありませんが，より良いアーカイブの名前を作ったりタグを追加するときに使われます．この例では，上流レポジトリにはfooパッケージだけがあるので，fooを入れるのが適切でしょう． （訳注：実際には，'upstream'のままにしているパッケージが多いし，そのほうが良いのではないかと思われる）

次は，上流レポジトリのURIを設定します．

Upstream Repository URI:
  <uri>
    Any valid URI. This variable can be templated, for example an svn url
    can be templated as such: "https://svn.foo.com/foo/tags/foo-:{version}"
    where the :{version} token will be replaced with the version for this release.
  [None]:

これは重要です！開発に用いている上流レポジトリのURIを入力してください．**リリースレポジトリではありません．** ここでは，GitHub上の組織barが持つレポジトリであるとして， https://github.com/bar/foo.gitを入力します．

次に，bloomは上流レポジトリのタイプを尋ねてきます．

Upstream VCS Type:
  svn
    Upstream URI is a svn repository
  git
    Upstream URI is a git repository
  hg
    Upstream URI is a hg repository
  tar
    Upstream URI is a tarball
  ['git']:

この例では，上流レポジトリはgitですが，他のVCS（svnとhg）や，tarといったアーカイブファイルもサポートされています．

次の2つのオプション(Version and Release Tag)はEnterを押してデフォルト値のままにしておいてください．catkinではないパッケージをリリースするためのもので，まれにしか使われません．

変更の必要があるかもしれないのは，次の上流レポジトリのブランチの設定です：

Upstream Devel Branch:
  <vcs reference>
    Branch in upstream repository on which to search for the version.
    This is used only when version is set to ':{auto}'.
  [None]:

このオプションは，リリースに用いたい上流レポジトリのブランチを設定します．デフォルトのNoneのままにしておくと，デフォルトのブランチが類推されて使われます．デフォルト以外のブランチを使いたい場合には，明示的に指定する必要があります．例えば，リリース・トラックのためにindigo-develブランチを使いたい場合，indigo-develと入力します．

次にROSのディストリビューションを入力します．

ROS Distro:
  <ROS distro>
    This can be any valid ROS distro, e.g. groovy, hydro
  ['indigo']:

このトラックが対象とするROSディストリビューションの名前を入力します．

残りの設定(Patches Directory and Release Repository Push URL)はほとんどの場合，デフォルトのままにしてきます．

おめでとうございます！これでリリース・トラックの設定が完了しました．

Bloomにはたくさんの派生コマンドがありますが，ほとんどの場合bloom-releaseだけで済みます．先頭にgit-が付いたbloomの派生コマンドがいくつか有りますが，これらはカレントディレクトリをgitレポジトリとして実行しなければなりません．リリースレポジトリを自分でcloneして，先頭にgit-が付いたコマンドで手動で細かく操作することができます．そのうちのgit-bloom-configはトラック管理のためのコマンドです．git-bloom-config -hでリリース・トラックを設定するためのより詳しい情報が得られます．

リリースの仕上げ

リリースレポジトリの設定が終わったら bloom-releaseはたくさんの処理をしますが，概ね，リリースレポジトリをcloneし，リリーストラックのactionsセクションにあるタスクをすべて行い，結果をpushし，最後にあなたに代わってpull requestを作成します．リリースレポジトリが正しく設定されていれば，bloom-releaseは処理を終えた後，あなたのGitHubパスワードを尋ねてきます．入力して処理が終わったら，新しく作られたpull requestへのリンクを表示します．

ビルドファームへの通知

通常，bloom-releaseはあなたに代わってpull requestを作成しますが，もし問題が起こったり，勝手にpull requestを作成されたくない場合には，手動でpull requestを作成することもできます．もしpull requestが自動でちゃんと作成されたのたら，下にあるように手動でpull requestを作成する必要はありません

ROSディストリビューションごとに固有のdistroファイルがGitHub上で管理されています．例えばhydroでは：

https://github.com/ros/rosdistro/blob/master/hydro/distribution.yaml

このファイルへのpull requestを送るには，単にこのURLにアクセスして，"Edit"ボタンをクリックし（注意：GitHubにログインしておく必要があります）,編集しおわたったらページ右下にある"Propose Changes"をクリックします．

あなたのレポジトリを設定するには，以下のようにセクションを入力します：

repositories:
  ...
  foo:
    tags:
      release: release/groovy/{package}/{version}
    url: https://github.com/ros-gbp/foo-release.git
    version: 0.1.0-0
  ...

リリースタグに正しいROSディストリビューション名（この場合groovy）を入力していることを確認してください．

上流レポジトリではなく，リリースレポジトリのURLをurlに入力することに注意してください．また，version番号には，あなたのパッケージのバージョンに，ハイフンで続くリリース番号を加えた，フルバージョン番号を入れなければなりません．リリース番号は同じバージョンのパッケージをリリースするたびに一つづつ増えていく番号で，リリースの設定を変えたり，リリースレポジトリにパッチを追加したりした際に増えていきます．さらに，あなたのパッケージをパッケージリストに加える際には，アルファベット順で加えるべきであることに，どうぞ留意ください．

repositories:
  ...
  foo:
    packages:
      foo_msgs:
      foo_server:
      foo_utils:
    tags:
      release: release/groovy/{package}/{version}
    url: https://github.com/ros-gbp/foo-release.git
    version: 0.1.0-0
  ...

ここでも，リリースタグには正しいROSディストリビューション名を入力してください．

注意： packagesのなかのリストは，コロン(:)で終わらなければなりません．パッケージへのパスがレポジトリのルートではない場合，コロンの後ろに指定します．例えば：

    packages:
      foo_msgs: util/foo_msgs
      foo_server: tool/foo_server

つぎのステップ

Pull requestが送られたら，ROS開発者の誰かがそれをマージしてくれるまでしばらく待ちましょう（だいたいすぐにやってくれます）．その後24−48時間後，あなたのパッケージはビルドファームでビルドされ，buildingレポジトリにリリースされます．ビルドされたパッケージは周期的にshadow-fixedと公開用レポジトリに同期され，しばらく後に（数週間かかることもあります）ROS debianレポジトリで公開されます．