Adds guidelines for project and service names
Change-Id: Ie585908069fa61efadf8b415cd6a5f95f9d5e204
This commit is contained in:
parent
0cf4af1859
commit
182ae0cf7b
@ -10,6 +10,7 @@ Reference documents which need to be revised over time.
|
||||
charter
|
||||
projects/index
|
||||
new-projects-requirements
|
||||
service-project-naming
|
||||
project-testing-interface
|
||||
irc
|
||||
release-naming
|
||||
|
77
reference/service-project-naming.rst
Normal file
77
reference/service-project-naming.rst
Normal file
@ -0,0 +1,77 @@
|
||||
==========================
|
||||
Service and Project Naming
|
||||
==========================
|
||||
|
||||
OpenStack projects must follow naming conventions for both the project team
|
||||
and the service the team provides. Following are some guidelines for
|
||||
reference to ensure consistency, reduce confusion, and enable documentation
|
||||
clarity.
|
||||
|
||||
Project Naming Process
|
||||
----------------------
|
||||
|
||||
The Technical Committee reviews the incoming project proposals through the
|
||||
openstack/governance repository with an update to the doc/source/reference/
|
||||
projects.yaml file. TC members should review the patches with these guidelines.
|
||||
|
||||
Project Name Guidelines
|
||||
-----------------------
|
||||
|
||||
When seeking a project name refer to the `Legal Issues FAQ
|
||||
<https://wiki.openstack.org/wiki/LegalIssuesFAQ>`_ on the OpenStack wiki.
|
||||
Realize the team name will not become a trademark.
|
||||
|
||||
In documentation on `docs.openstack.org <http://docs.openstack.org>`_, project
|
||||
names are consistently lowercase, such as nova and keystone. The documentation
|
||||
also uses lowercase when referring to file names such as `nova.conf`, and when
|
||||
referring to the Command Line Interfaces (CLI) for those projects including
|
||||
the ``openstack`` CLI command.
|
||||
|
||||
The history of this decision is that the documentation contributors wanted the
|
||||
least amount of cognitive overhead when writing and reviewing. Learning rules
|
||||
about case can be difficult across multiple projects and with hundreds of
|
||||
documentation contributors and thousands of changes and additions. Lowercase
|
||||
for project names as a rule is then easiest to review and enforce at this scale
|
||||
and growth pattern.
|
||||
|
||||
Service Name Guidelines
|
||||
-----------------------
|
||||
|
||||
When naming the service that your project provides, please consider the use
|
||||
of the service name in documentation for operators, administrators, end-users,
|
||||
and developers consuming the service. The current convention is:
|
||||
|
||||
* Use service in documentation to further clarify what the project offers.
|
||||
* Use an initial capital for all words in the service name, including the word
|
||||
after a hyphen.
|
||||
* Do not use OpenStack in the name of the service. Certain other words may
|
||||
be reserved also due to trademark, but we have had examples of getting
|
||||
permission such as Puppet.
|
||||
|
||||
Examples of these guidelines in service names are: the Block Storage service
|
||||
(cinder), the Object Storage service (swift), or the Bare Metal service
|
||||
(ironic).
|
||||
|
||||
Review Guidelines
|
||||
-----------------
|
||||
|
||||
Early in the OpenStack history, service names in
|
||||
combination with the brand name "OpenStack," were thought to be legally
|
||||
binding. However, as more services are added, the complexity of the names of
|
||||
services has increased. So, while the names are considered proper nouns, naming
|
||||
conventions do not indicate a legal right to the name.
|
||||
|
||||
If you have a question about legal use of the OpenStack name or logo, refer to
|
||||
the `OpenStack Brand website <http://www.openstack.org/brand>`_. Refer to
|
||||
`Documentation Conventions <https://wiki.openstack.org/wiki/Documentation/Conventions#Service_and_project_names>`_
|
||||
and ask for guidance on the openstack-docs mailing
|
||||
list if you have questions about using the names in context. As a final
|
||||
arbitration or decision point, refer to the `IBM Style Guide <https://www.redbooks.ibm.com/Redbooks.nsf/ibmpressisbn/9780132101301?Open>`_
|
||||
as it is the final decision point for spelling or usage of a term.
|
||||
|
||||
Developer documentation may refer to the project name, but end-user, operator,
|
||||
administrator, and application developer documentation must refer to the
|
||||
service name. When reviewing service names, consider the consumers of the
|
||||
information.
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user