OEP: 3 Title: Naming Conventions and Repository Structure Author: Brian Bingham Status: Active Type: Process Content-Type: text/x-rst Created: 14-Apr-2016 Post-History: 14-Apr-2016

3   Naming Conventions and Repository Structure

3.1   Organization of Repositories on Bitbucket

Currently bitbucket is hosting all OER repositories. Within bitbucket the following three hierarchical organizations are supported:

  1. Teams: All OER repositories should be owned by the noaarov team.
  2. Projects: Within the OER team, repositories are organized into projects. Each repository is associated with one, and only one, project. The naming of projects is fluid, but the following standard project associates are
    1. oer is the highest level project for general purpose software tools. For example, this repository of OEPs is in the oer project because it is applicable to all OER projects. If a software package is useful in multiple projects it should be a part of the oer project.
    2. d2 is a vehicle specific project for D2. Software packages that are specific to this vehicle should be a part of this project.
    3. minirov is a vehicle specific project for the minirov. Software packages that are specific to this vehicle should be a part of this project.
  3. Users: In general, OER projects should not be owned by individual users. In the past the OER team has used the rov337 bitbucket user as a common owner for all repositories. Moving forward it is recommended that the team move all repositores to the noaarov team.

3.1.1   Permissions

In the short term it seems to make sense have all OER developers be Administrators of the noaarov bitbucket team. In the future, as the team grows, this policy may prove to be overly permissive, but for now everyone should have full rights.

All repositories should be public.

3.2   Repository and Package Naming Conventions

Individual sofware components are typically organized as Python packages and the source code is stored in a repository. Components will also typically have executables associated with them that make use of the package and associated modules.

The naming convetions we use are adaptations of PEP8 , The Hitchhiker’s Guide to Python and the Packaging Python Libraries chapter of Dive Into Python 3 which are the guidelines for PyPI.

3.2.1   Package Naming

Unless there is a good reason not to, package names should follow these constraints:

  • All lowercase.
  • Unique. If you think your name might not be unique, search for it in the PyPi and ROS indicies.
  • When multiple words are needed, an underscore should separate them. Don’t use hypens or spaces. (Note that PEP8 says, “use of underscores is discouraged”. We are less prescriptive about this. You should choose between a singleword solution and multiple_word solution based on readibility.)

In general package/repository names should become increasingly specific as you read from left to right. This arrangement supports effective sorting by name.

3.2.2   Repository Naming

The repository should use the same name as the package, except that they repository substitutes dashes (-) for underscores (_).

3.2.3   Executable Naming

Executables should also use dashes as word separators.

3.2.4   Example

Here is an example of how we might organize a repository called `altimeter-valport-lcm` which contains the package `altimeter_valeport_lcm`. The package contains the module `altimeter_valeport_lcm.parser`

altimeter-valeport-lcm/
├── altimeter_valeport_lcm
│   ├── parser.py
│   ├── __init__.py
│   └── __main__.py
├── README.rst
└── setup.py

The setup.py file contains a line such as

entry_points = {
      'console_scripts':
        ['altimeter-valeport-lcm=altimeter_valeport_lcm.__main__:main'],
        },

which generates the executable `altimeter-valeport-lcm`.

3.3   Naming Conventions by Component Type

3.3.1   User Interfaces

I’ll leave this to Andy

3.3.2   Libraries and Utilities

Code that is generally useful across multiple other packages/modules should typically be named with three underscore-separated parts: TYPE_DESCRIPTION where

  • TYPE is one of {utils, lib, defs} where
    • utils denotes a collection utility programs. Utilities are most often standalone exectuable programs meant to be used by a developer as opposed to libraries/modules which are meant to be used within another program. For example, “utils_lcm_python” might contain executable python programs that
    • lib denotes libraries or modules that contain OER shared objects, functions and methods that are commonly used in other OER programs. For example “lib_timestamp_python” might contain python modules for dealing with OER-compliant timestamps.
    • defs denotes definition files that are common to multiple OER packages. This is where message and service definitions should reside. For example “defs_minirov_lcm” would be expectd to contain LCM message definitions that are specific to the MiniRov project. “defs_general_lcm” might be expected to contain the most basic, broadly applicable LCM definitiosn for OER software.
  • DESCRIPTION is self explanatory

3.3.2.1   Examples

  • utils_lcm
  • defs_lcm_general

3.3.3   Drivers

In the context of OER software “drivers” are the layer of software between hardware devices (e.g., external sensors, onboard I/O, etc.) and the internal communications (e.g., LCM or ROS).

Driver names should typically consist of three parts, each separated by an underscore: TYPE_NAME_COMMUNICATION where

  • TYPE is the general description of the class of device with which your driver will interface. The TYPE might be the general name of the sensor (e.g. compass, imu) or the thing being measured (e.g., ctd, depth, altitude, analogin). The some cases a single device measures multiple things, e.g., an OceanServer compass module that also reports depth or the Valport altimeter that also reports pressure (depth). In most cases there is a primary type that should be used, e.g., “cmpass_os_lcm_cpp” or “altimeter_valeport_ros_python”.
  • NAME is the specific description of the particular device with which your driver is designed to communicate. The NAME might be the mdel of the device (e.g., tcmxb) or the vendor of (e.g., rdi, rowe). The NAME should be specific enough to map to the communications interface that your driver implements. For example, using “ctd_seabird_lcm_python” may not sufficiently specific because Sea-bird makes a a bunch of different CTDs with a variety of CTD sensors. Based on the name “ctd_seabird_lcm_python” we would expect that this package/driver is capable of communicating with a variety of devices. If your driver is specific to a particular model and interface type, say for the SBE 49 FastCAT RS232 interface, you should include that specificity in the NAME: e.g., “ctd_seabird49_lcm_python”
  • COMMUNICATION is the middleware communication used by the driver. As of this writing this will be one of {lcm,ros}

3.3.3.1   Examples

  • dvl_rdi_lcm
  • dvl_rowe_ros
  • ctd_seabird49_lcm
  • altimeter_valeport_lcm

3.4   Organization of Package/Module within a Repository

See the Packaging Python Libraries chapter of Dive Into Python 3 which are the guidelines for PyPI.

3.5   Packaging and Release Distribution

OER is still working towards a standard solution for packaging and distributing Python projects. At the time of writing there are at least two possibles:

  1. We could use devpi as a private packaging, testing and release server http://doc.devpi.net/ This would entail using setuptools for building and distributing packages https://pythonhosted.org/setuptools/setuptools.html If we use LCM this would likely be an attractive method.
  2. We could use ROS packages to achieve the same (or similar) functionality.

For now this issue is tabled until Andy has time investigate further. Note that how we organized repositories depends on this choice!

3.6   Naming Conventions for Communications

The guidelines below apply to the communication middleware used in OER projects. It would be beneficial if the conventions applied equally to either LCM or ROS.

3.6.1   Message Type Naming Conventions

Coming soon

3.6.2   Channel/Topic Naming Conventions

Coming soon