Merge pull request #94 from vrabaud/master

REP about package naming conventions

Merging as draft.

rep-0144.rst

@@ -0,0 +1,136 @@
+REP: 144
+Title: ROS Package Naming
+Author: Vincent Rabaud <vincent.rabaud@gmail.com>
+Status: Draft
+Type: Informational
+Content-Type: text/x-rst
+Created: 28-Jan-2015
+Post-History:
+
+Abstract
+========
+
+This REP gives advice on how a ROS package should be named.
+It formalizes and extends conventions that were formerly described in [1]_.
+
+Motivation
+==========
+
+As the number of ROS packages increases, it is hard to quickly find a package
+and guess its functionality based on its name.
+Over time, the lack of naming conventions created problems like use of
+unexplained acronyms or packages with the same functionality but different names.
+
+For now, ROS package names translate directly to packages in supported Operating
+Systems: therefore, there is a flat global namerspace in which rules have to
+be followed.
+
+This REP proposes rules to name a ROS package properly.
+Some of those rules are mandatory, others merely advised.
+
+Package Naming
+==============
+
+Mandatory Rules
+---------------
+
+By habit, a package name is often used as a namespace (in C++ or any other language).
+Thus, the naming rules have to be strict.
+
+* ``alphanumerics`` are ``a-z0-9`` only
+* ``alphabetics`` are ``a-z`` only
+* it must only consist of alphanumerics and ``_`` separators.
+  Other symbols might not be supported by some OSes (e.g. unicode characters) or would
+  make it hard to follow OSes conventions/
+* they must be at least two characters long and must start with an alphabetic character.
+  This rule is simply to force the name of the package to be more human understandable.
+
+Global Rules
+------------
+
+* package names should be specific enough to identify what the package does.
+  For example, a motion planner should not be called ``planner``.
+  If it implements the wavefront propagation algorithm, it might be called
+  ``wavefront_planner``.
+  There's obviously tension between making a name specific and keeping it from becoming
+  overly verbose
+* using catchall names such as ``utils`` should be avoided as they do not scope what goes
+  into the package or what should be outside the package
+* a package name should not contain ``ros`` as it is redundant.
+  Exceptions include core packages and ROS bindings of an upstream library
+  (e.g. ``moveit_ros``)
+* one of ROS's goals is to develop a canonical set of tools for making robots do
+  interesting things.
+  The package name should describe what the package does, not where it came from.
+  Then again, as stated in the rules below, ``if a package is specialized
+  by an entity (lab, company, ...), prepend the name of the entity``.
+  But once the package is commonly used, owned and maintained, that name can be dropped
+  as the package becomes the reference
+* to check whether a name is taken, consult [2]_. If you'd like your
+  repository included in that list, see the tutorial at [3]_
+
+Naming Rules
+------------
+
+The following rules define the different parts of the package name.
+The overall idea is to prepend a name with words that distinguish it from similar 
+functional implementation (e.g.: ``lab``, ``robot``) but in order of importance 
+(e.g.: ``python_robot_lab``).
+Similarly, words that specialize this functionality are appended
+(e.g. ``msgs``, ``config`` ...).
+
+The rules to add those words should be followed in order.
+For prefixes:
+
+* if a package is specialized by an entity (lab, company, ...), prepend the 
+  name of the entity.
+  Once the package is commonly used, owned and maintained, that name can be dropped
+* if a package is specialized for a software project, prepend its name
+* if a package is specialized for a hardware piece, prepend its name
+* if a package is specialized for a robot, prepend its name
+
+For suffixes:
+
+* if a package is a driver, append ``driver``
+* if a package contains any of a ROS message/service/action, append ``msgs``
+* if a package is a plugin for a library, append ``<library_name>_plugins``, e.g. 
+  ``pr2_gazebo_plugins``
+
+Special Suffixes:
+
+* a meta package for a robot should be named ``<name_of_the_robot>_robot``, e.g. 
+  ``pr2_robot``
+* a package containing the URDF and meshes of a robot should be named 
+  ``<name_of_the_robot>_description``, e.g ``pr2_description``
+* if a package is meant for test only, prepend ``test``
+
+Special Cases
+-------------
+
+* a package containing only a set of launch files should end with ``launch``
+* a package containing only a set of launch files whose goal is to start a robot
+  should end with ``bringup``
+* a package containing one or more tutorials only should end with ``tutorials``.
+  If it is a set of tutorials for another package, it should contain that other
+  package name: e.g. ``navigation`` and ``navigation_tutorials``
+* a package containing one or more demos only should end with ``demos``
+* third party libraries that are patched / integrated into ROS should not be named
+  like their rosdep key as it creates a conflict across Ubuntu versions.
+  If it is not specialized, name it generically ``<name_of_library>_ros``
+
+References
+==========
+
+.. [1] ROS Pattern Conventions
+   (http://wiki.ros.org/ROS/Patterns/Conventions#Packages)
+
+.. [2] Browsing ROS Packages
+   (http://www.ros.org/browse)
+
+.. [3] Indexing Your ROS Repository for Documentation Generation
+   (http://wiki.ros.org/rosdistro/Tutorials/Indexing%20Your%20ROS%20Repository%20for%20Documentation%20Generation)
+
+Copyright
+=========
+
+This document has been placed in the public domain.