首次发布功能包

Contents

首次发布功能包

本指南将帮助你使用bloom和catkin工具发布一个全新的ROS包。默认情况下，bloom将向公共的ROS 构建工厂发布包，这是本教程所教你做的。有关发布包的更多信息和策略，请参见http://build.ros.org。

发布准备

安装 bloom。你可以用它来发布你的包。
确保您的代码是最新的，所有的测试都通过了，并且你已经将所有的更改从你的机器push到上游存储库。上游存储库是你开发和托管包的源代码的存储库。这个存储库可以托管在任何地方(甚至本地)，也可以是一个git、hg或svn储存库，也可以是一个归档文件的位置(现在是tar.gz，但是还有tar.bz和zip)。

Bloom对发布你的包有一个重要的要求。如果你的上游存储库是vcs (git、hg或svn)，那么它必须具有与你打算发布的版本相匹配的tag。例如，如果你打算发布包的0.1.0版本，那么bloom期望在你的上游存储库中有一个0.1.0的tag。如果你跟随教程的其他部分，这个tag将自动为你完成，所以现在不需要你自己去做。

如果你有一个你想要使用的自定义版本tag计划，那么bloom可以在配置发布跟踪(见下)时使用' release Tag'配置来处理。
(如果发布ROS1)，执行预发布测试通过后,遵循预发布介绍。这一步是可选的(只适用于ROS1)，但强烈推荐。预发布将确保你的包构建和测试在安装在另一台机器上(技术上是在Docker容器上)时传递。运行预发布测试将减少你的痛苦，以防你的发布有任何问题。

准备上游存储库

这个页面将指导你通过设置你的存储库来创建一个Bloom的release版本。

注意: 由于ROS2使用了一个新的构建系统，所以这个过程不适合ROS2包。如果使用ROS2，你将不得不自己创建changelog并释放标记。请查看在ROS2 wiki上的Bloom Release页面得到更多信息。

更新Changelogs

它们不是强制的，而是推荐的：(ref: REP-132).

生成一个Changelog

```
$ catkin_generate_changelog
```

运行catkin_generate_changelog来生成或更新CHANGELOG.rst 文件。如果一个或多个包不包含CHANGELOG.rst, 添加--all选项来为每一个包填充所有的注释。

清理Changelog

命令catkin_generate_changelog只是简单的把git的提交记录填充至Changelog中,这些日志并不总是适合于变更日志。打开CHANGELOG.rst文件按照你自己的格式进行日志变更说明。这是一个CHANGELOG.rst的良好示例.

不要忘记进行下一步!

注意: 不正确的CHANGELOG.rst将会导致包的一些问题。

注意: 如果你有任何以下划线结尾的提交消息，例如成员变量(例如:name_)这将使RST Changelog格式出现错误，因为RST将其视为超链接。这有可能出现以下错误：

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

想要修复这个，你需要避免变量，例如:

* fix for checking the ``name_``

提交

这个步骤非常重要,不要忘记! 检查新建或更新的changlog。

注意: catkin_generate_changelog的一些额外信息, 例如命令行标志,可以在原始的讨论话题中找到 ( $/!\$ 这个参考最终应该被一个更权威的文档所取代，而不是一个电子邮件讨论思路)

更新package.xml版本

你必须在你的包里package.xml里更新这个版本。在你的上游存储库中创建匹配该版本的tag。catkin提供了一种工具，称为catkin_prepare_release:

$ cd /path/to/your/upstream/repository
$ catkin_prepare_release

这个命令将在你的上游存储库中找到所有的包，检查它们是否有changelogs(然后它们没有未提交的本地更改)，在你包的package.xml中增加版本，并使用bloom兼容的标志commit/tag更改。使用此命令是确保你的包具有一致和建议的发布的最佳方法。

默认情况下，这个命令会增加包的补丁版本。例如：0.1.1 -> 0.1.2，但你可以使用--bump选项来选择小的或专业的版本。

即使你不使用catkin_prepare_release，你也必须有一个或多个有效的package.xml，在你的上游存储库中有相同的版本和一个匹配的tag。

创建发布存储库

下一步是创建一个release存储库。Bloom要求你有一个单独的"release"存储库来发布你的包。这个存储库必须是一个git存储库，通常由一个服务(如GitHub)来托管。例如，所有的ROS发布存储库都在ros-gbp github组织中。这些存储库是在包含一个或多个catkin包的存储库上运行bloom的结果。

我们强烈建议你在GitHub - https://github.com上托管你的release存储库。本教程使用GitHub，但你也可以在本地创建release存储库并将其托管到其他地方。

在github.com创建release存储库

在github组织或你选择的github用户上创建一个新的存储库。按照惯例，你应该将其命名为-release后缀的包名。因此，对于ros_comm存储库，相应的发布存储库称为ros_comm-release。注意:当创建你的github.com存储库时，请选中使用README初始化该存储库。这样，它以一个有效的git repo开始。Bloom稍后将在这个文件中添加关于发布版本的信息。

创建了这个新的发布存储库之后，就可以配置和发布包了。从github页面获取release存储库url，因为接下来需要它。

发布你的包

注意: 如果在github上,你有两个因素需要授权,请首先遵循这个教程: Github手动授权

通常你需要像如下这样：

# 这是个样例，不要运行这个，运行另一个
$ bloom-release --rosdistro <ros_distro> --track <ros_distro> repository_name

为了从存储库中发布包，但是在第一个版本中(并且任何时候你想要配置一个新的'track'设置)，你将需要添加—edit选项:

# 替换 <ros_distro> 为当前ROS版本，例如：indigo
$ bloom-release --rosdistro <ros_distro> --track <ros_distro> <your_repository_name> --edit

此选项将允许你编辑在发布之前指定的跟踪。这是第一次发布时需要的，因为你还没有跟踪，所以bloom将首先为你创建一个，然后允许你配置它。请注意，repository_name不是它的url，而是它在distribution.yaml中的引用。

当你运行上述命令时，它将会到ROS distro的ROS发行版文件，该文件内容为你指定并查找存储库的信息。因为这是你的第一个版本，所以它不会找到你的存储库的信息，所以它会向你请求发布存储库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]?

点击 enter 或输入 'y' 后敲入 enter 继续。

现在bloom将配置一个master分支(这是存储配置的地方)，并开始提示你有关发布的信息。

配置发布追踪

bloom旨在允许在同一个发布存储库中为不同的ROS发行版本和版本发布相同的包。为了促进这一点，bloom使用发行版"跟踪"来维护不同发布过程的配置。对于正常的基于catkin的ROS包，建议使用默认的发布跟踪。

在你上面运行的bloom-release命令中，你指定了--track。按照惯例，你应该创建与你所发布的ROS发行版相同名称的名称，但你可以指定你想要的名称。

提供给你的第一个问题是存储库名称:

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

这个名称很简单，但是可以用来提供额外的tags并创建更好的存档名称。由于我们的示例在存储库中有一个名为foo的包，所以在这里输入foo是合适的。

接下来配置的是上游存储库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放在进行开发的位置上。这不是你打算托管这个release存储库的地方。在这种情况下,我会假装我们的代码托管在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，但也支持svn、hg和tar存档。

接下来的几个选项(Version和Release Tag)应该可以作为默认值离开，除非你正在释放一个非catkin包，否则很少更改。只需按enter键接受默认值即可。

你需要修改的下一个选项是上游开发分支:

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]:

这个选项是你的上游存储库的分支，你可以从tag中发布。如果这没有留下，那么当猜测版本被发布时，就使用默认分支。如果你想在默认分支之外搜索分支，请选择该分支。例如，如果你想使用分支indigo-devel来进行这个发布跟踪，请输入indigo-devel。

下一个ROS发行版是必需的:

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

输入此跟踪所基于的ROS发行版的名称。

其余的配置(Patches Directory和Release Repository Push URL)在大多数情况下都是默认的。

祝贺你，你已经成功地配置了你的发布跟踪。

尽管你很可能只需要运行bloom-release，但有许多命令会伴随bloom而来。许多bloom命令都使用git-前缀，这表示它们必须在git存储库中运行。如果你手动克隆发布存储库，那么你可以使用git-前缀来手动操作你的发布存储库。其中一个命令叫做git-bloom-config，它可以让你管理你的跟踪。运行git-bloom-config -h以获得更多关于如何管理发布跟踪的信息。

完成发布

在完成配置存储库之后，bloom-release将会做很多事情，但通常它是克隆你的发布存储库，执行在你的发布跟踪的actions部分中定义的所有发布任务，从而推动结果，并最终为你打开一个pull请求。如果你正确配置了你的发布存储库，那么你的bloom版本最终将会成功，这将会提示你github凭证。一旦完成，它就应该为你提供与新创建的pull请求的链接。

通知构建工厂

正常情况下，你的bloom-release调用应该为你打开一个pull请求，但是如果存在问题，或者你不希望它为你打开pull请求，你也可以手动打开一个pull请求。如果自动打开的请求被成功打开，那么你不需要手动打开，如下所述。

对于每个ROS分布，有一个在Github上托管的发行版文件，对于hydro来说:

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

你可以通过访问上面的URL并单击edit按钮来打开这个文件的pull请求(注意:你必须登录到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)。

注意，你应该将https://的url放在这里，而不是源存储库的url。还要注意，你必须将包的完整版本(即包的版本)加上由连字符分隔的释放增量号。每次发布相同版本的包时，都会增加释放增量号，这可能发生在向发布存储库添加补丁或更改发布设置时。还要注意，请你应该按照字母顺序将包放入包的列表中。

注意: 如果你的存储库包含多个包，他们的名字也必须列举在distro文件中：

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:
      foo_msgs: util/foo_msgs
      foo_server: tool/foo_server

接下来

一旦提交了pull请求，其中一个ROS开发人员将合并你的请求(这通常会很快发生)。24-48小时后，你的包应该由build farm构建并被释放到构建储存库中。构建的包会定期同步到shadow-fixed和公共存储库同步，因此，在你的包在公共ROS debian存储库(即通过apt-get可用)上提供之前，可能需要长达一个月的时间。要在下次同步到来时获得更新，请检查ROS 讨论论坛。