4.3 KiB
Naming an Oslo Library
Choosing a good name for a new Oslo library is important because the name can be used to signal how we intend the library to be used. This page describes the guidelines we use when choosing a new name.
Problem Description
Library names need to convey the purpose of the library, as well as the intended audience.
Proposed Policy
The Project Creator's Guide includes guidelines for finding unique names with valid character sets and other technical criteria. This policy extends those guidelines to cover some criteria that are unique to Oslo.
There are currently three naming schemes used for Oslo libraries.
Production Runtime Dependencies Meant for OpenStack
Libraries used for production runtime dependencies of OpenStack
projects should follow the naming pattern oslo.something
for the library and dist, but use oslo_something
for the
top level package name. Avoid using the oslo.
namespace
package (../kilo/drop-namespace-packages
).
Examples of production runtime dependencies include
oslo.config
and oslo.messaging
.
Non-production Dependencies Meant for OpenStack
Libraries used for non-production or non-runtime dependencies of
OpenStack projects should follow the naming convention
oslosomething
(leaving out the .
between
"oslo" and "something") for the library, dist, and top level
package.
Examples of non-production dependencies include
oslosphinx
and oslotest
.
Note
If you are planning to use a name like this, please discuss it with the Oslo team first - we aren't sure we like this name scheme and may suggest an alternative.
Everything Else
Libraries that may be generally useful outside of OpenStack, no matter how they are used within OpenStack, should be given a descriptive and unique name, without the "oslo" prefix in any form.
Other examples of Oslo names include pbr
and
taskflow
.
Alternatives
Always Use a Generic Name
One alternative is to use all generic names, without the "oslo"
prefix. The main drawback of this approach is that it lacks the ability
to signal our intended audience for the library. Some of the libraries
we build are not useful to an audience working outside of OpenStack.
That could be because it is unencumbered with dependencies on
OpenStack-specific libraries such as oslo.config
, uses
patterns not used elsewhere, or is simply unlikely to be of interest to
anyone else. Using the "oslo" prefix gives us a way to indicate to the
rest of the Python community that the library is meant primarily for use
in OpenStack.
Non-production Libs to Use "oslo." Prefix
As mentioned above, the Oslo team is not entirely happy with names
like oslotest
and oslosphinx
. The decision to
use the prefix without the dot separator comes from the fact that those
libraries were not installed into the old "oslo" namespace package. The
library names were selected to be consistent with the package name used
in import statements, and we've kept those names rather than going
through the trouble of renaming a library like oslotest, on which much
of OpenStack relies.
Implementation
Author(s)
Primary author: doug-hellmann
Milestones
Effective from the Icehouse release.
Work Items
N/A
References
Revision History
Release Name | Description |
---|---|
Icehouse | Introduced |
Note
This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode