[Documentation] [TitleIndex] [WordIndex

首次发布功能包

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

发布准备

  1. 安装 bloom。 你可以用它来发布你的包。

  2. 确保您的代码是最新的,所有的测试都通过了,并且你已经将所有的更改从你的机器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'配置来处理。

  3. (如果发布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手动授权

通常你需要像如下这样:

为了从存储库中发布包,但是在第一个版本中(并且任何时候你想要配置一个新的'track'设置),你将需要添加—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,但也支持svnhgtar存档。

接下来的几个选项(VersionRelease 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 DirectoryRelease 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 讨论论坛


2022-05-28 12:29