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
(Drop our use of 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¶
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
