12c5438f43
The file name should be marked follow [1] as consistent with their semantic meaning. [1] https://docs.openstack.org/doc-contrib-guide/rst-conv/inline-markups.html#file-name-and-path Change-Id: Ief3c3960034fe76fe2e3b2deda45ffd7906966db
3.5 KiB
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 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.