From 182ae0cf7b948f418e0f4493f141b6e3165f2e31 Mon Sep 17 00:00:00 2001 From: Anne Gentle Date: Mon, 13 Jul 2015 09:45:10 -0500 Subject: [PATCH] Adds guidelines for project and service names Change-Id: Ie585908069fa61efadf8b415cd6a5f95f9d5e204 --- reference/index.rst | 1 + reference/service-project-naming.rst | 77 ++++++++++++++++++++++++++++ 2 files changed, 78 insertions(+) create mode 100644 reference/service-project-naming.rst diff --git a/reference/index.rst b/reference/index.rst index 91aed0f24..e5483bf5d 100644 --- a/reference/index.rst +++ b/reference/index.rst @@ -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 diff --git a/reference/service-project-naming.rst b/reference/service-project-naming.rst new file mode 100644 index 000000000..4ad2063a6 --- /dev/null +++ b/reference/service-project-naming.rst @@ -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 +`_ on the OpenStack wiki. +Realize the team name will not become a trademark. + +In documentation on `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 `_. Refer to +`Documentation Conventions `_ +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 `_ +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. + +