第二十二章 ROS 在线社区

本书的主要编写目的在于讲解组成 ROS 系统的各个软件和工具库, 并鼓励读者在机器人项目中使用ROS. 然而, ROS 吸引人的地方不仅仅在于它的技术价值本身, 还在于 ROS 背后的庞大生态-- ROS 社区. 就像大多数开源项目一样, ROS 离不开社区的贡献. 作为一个仍在不断开发和完善中的项目, 来自世界各地的开发者们正在不断地维护, 改进和扩展 ROS 的代码和文档. 本章中, 我们会介绍 ROS 社区里的一些在线资源. 希望能帮助你融入 ROS 社区, 成为 ROS 开发者的一员.

社区的礼仪

首先要强调的是在线社区的基本礼仪. 保持礼貌不难, 就像日常生活中一样, 合乎基本的礼仪习惯即可. 不过, 如果有些分寸没把握好, 也很容易造成困扰. 下面是在线社区中的一些基本礼仪习惯, 请牢记在心:

• 保持对社区伙伴的信任. 请记住, 你找到的 bug 只是其他人不小心犯的错误, 遗漏的文档只是一时疏忽, 回复的不及时仅仅是因为太忙. 哪怕是你收到了看起来有点尖酸刻薄的回应, 那也不过是你误解了别人的本意而已. 正所谓"海纳百川, 有容乃大", 对于社区, 我们要保持足够的耐心和宽容, 这样才能让社区不断快速成长.
• 不要在邮件列表或论坛里问重复的问题. 没有收到回复不代表别人没看见, 可能是大家太忙, 也可能是你的问题太难. 但无论是哪种情况, 重复提问都是一种很糟糕的习惯.
• 不要给你的问题加上诸如"急需","急求"这样的标题. 更不要以个人的原因(比如项目或家庭作业的期限)为由请求他人尽快回答. 这样不仅得不到任何同情, 还会招致他人的反感, 从而使你的问题更不能得到及时的回复.

建立社区的意义在于让 ROS 一步一步走向更大的成功. 毋庸置疑, 真诚, 友好的合作将会使社区的效用最大化.

ROS 维基

ROS 在线社区的中心是 ROS 维基. ROS 维基包括对ROS 整体的介绍(如安装指南)和每个 ROS 包的技术文档, 包括本书中涉及的所有软件和工具库. ROS 维基也是其他ROS在线资源的入口, 如代码仓库和 bug 追踪器等等.

ROS 维基的主要组成部分是每个 ROS 包的页面. 它们的 URL 是: http://wiki.ros.org/<package name>. 例如你想查看 rospy 这个包的文档, 可以直接访问 http://wiki.ros.org/rospy?distro=indigo. 页面的组成大致相同, 包括自动从包的元数据中生成的基本信息和一些其他内容. 一个内容完善的页面除了会对包的目的的使用方法做介绍外, 还会提供一些相关资源的链接, 如教程, 常见问题, 开发日志和 API 文档等等.

每个人都可以对维基进行编辑, 包括你. 我们需要靠社区的力量来不断完善ROS 维基. 当然, 开发者理应承担撰写文档的主要责任, 但是你同样可以让这些文档变得更好. 所以, 当你看到了完善文档的机会, 无论只是对排版的微小调整, 还是增加一篇全新的教程, 就请去大胆的尝试吧!

图22-1 ROS 维基: ROS 软件的文档和信息中心

ROS Answers: 一个 ROS 问答社区

当你在使用 ROS 的过程中遇到问题时---从"X 该怎样做", 到"为什么 Y 不能得到 Z 这样的运行效果", 你都应该去 ROS Answer 上看看. ROS Answer 是一个类似 Stack Overflow的问答平台, 只不过问题的范围集中在 ROS 方面. 毫无疑问, ROS Answer 是你提问的最佳去处之一.

图22-2 ROS Answers: ROS 社区的问答平台

提问之前, 请先在平台上搜索, 确保之前没有人提过相同的问题. 如果确实找不到再提问. 高质量的提问是得到有效回复的重要保证, 下面是一些提问时需要注意的地方:

• 尽可能详细的描述问题, 如果你在问有关一件事情的做法, 那么请尽可能多的提供问题的背景, 包括你的目标等等, 这样别人才能给你提供一种可行的办法. 如果你问的是一些异常现象的成因, 那么请提供复现该问题的步骤.
• 适当提供辅助信息. 如错误/警告消息, 相关代码片段, 程序堆栈, bag, 日志文件, 图片和视频等等.
• 提供版本信息. 至少要提供你使用的 ROS 发行版名称(Hydro, Indigo 等). 针对问题的不同, 可能还要提供你使用的 ROS 包名和版本号, 操作系统和硬件信息等.
• 在问题中附加辅助信息时请尽量进行拷贝而不是自己重新输入一遍. 因为哪怕一些微小的拼写错误都可能会带来很大的不同.

跟维基一样, ROS Answers 也是任何人都可以编辑的. 如果你知道这个问题的答案, 那就请展现你的智慧吧!

Bug 追踪与新特性请求

有时候, 你在 ROS Answers 上得到的回复可能是这样的: "嗯, 这看起来是一个 Bug", "不, 这个功能还没有实现". ROS 作为一个开发中的项目, Bug 和未实现的特性肯定是有的. 这个时候, bug 追踪平台就派上用场了.

由于 ROS 代码天生的分布特性, ROS 没有一个集中式的 bug 追踪平台, 不过, 每个包一般都会有自己的 bug 追踪平台. 当发现问题时, 首先定位到一个具体的 ROS 包(如果是在找不到, 就猜一个可能性最大的), 然后到这个包的维基页面上找到 bug 提交的链接. 如果维基页面上没有给出 bug 追踪平台的链接, 那说明你可能需要到代码仓库的托管平台上去提交 bug(比如一个托管在 GitHub 上的ROS包一般就会使用GitHub提供的 bug 追踪平台).

发起一个 bug 汇报/新特性请求前, 请参照前一小节中在 ROS Answers 上提问的注意事项修改你的措辞. 如果可能的话, 请附上一份补丁. 一般来说, 附有补丁的汇报/请求比较容易得到及时的回复.

ROS 的 bug 追踪平台同样是开放的. 如果你发现了代码中的问题, 或者是某个未被实现的特性, 而你又能解决它们的话, 就请去试试吧!

邮件列表与ROS兴趣小组

ROS 的主邮件列表是 [email protected]. 归档的邮件可以在 http://lists.ros.org/mailman/listinfo/ros-users 上找到. 这个邮件列表主要用于发布通知. 因此如果你想要发布一个 ROS 包, 或者举办一个跟 ROS 有关的活动的话, 可以向这个邮件列表发邮件. 另一方面, 如果你想咨询 ROS 使用上的问题, 或者汇报 bug, 请访问 ROS Answers 或 bug 追踪平台.

ROS 社区中, 有许多关注特定领域应用的子社区, 包括嵌入式系统, 驱动开发, 机械臂等等. 这些子社区自发组成了许多兴趣小组(Special Group of Interests, SIGs), 目前比较活跃的小组列表可以在维基上查看.

查找和分享代码

就像 bug 追踪平台一样, ROS 没有一个集中的代码仓库. ROS 的代码大多以包为单位, 存放在不同的仓库里.这种做法最大程度的保证了代码存储, 部署和分发过程中的灵活性. 因此, 如果想访问一个包的代码仓库, 请到相应的维基页面上寻找链接.

人们经常会问"如何向 ROS 贡献我自己写的包?". 答案是, 将你的代码放在一个公开的代码仓库里, 然后在社区里告诉大家. 你可以选择你喜欢的代码托管平台和版本控制工具(我们推荐使用GitHub, 这也是绝大部分 ROS 包选择的代码托管平台), 只要在维基里写明即可. 关于具体的实施细节, 可以参考 ROS 维基上的教程. 请记住, ROS 是个分布式的项目, 如果不能在社区里广而告之, 那么就谈不上"向 ROS 贡献代码"了.因此请务必主动宣传自己的工作.

小结

本章中, 我们探讨了 ROS 社区和一些在线资源.在上面, 你可以提出问题, 汇报 bug, 或发布你自己的包. ROS 是一个开放的项目, 需要大家的通力协作才能得到更好的发展. 主动融入社区吧! 让我们看到你为 ROS 做出的贡献.