Re: [openstack-dev] Should project name be uppercase or lowercase?
On 07/07/2015 10:36 PM, Anne Gentle wrote: > How do you think which should we use uppercase vs lowercase for > representing project names? > > > I'll be patching the governance repo with some guidelines we have been > using to make them official. The projects.yaml file is the reference > point for the service catalog and documentation, and the doc team > maintains a lookup list on the wiki page referenced above. > > Conventions for service names: > > * Uppercase first letter of first word only. > * Do not use OpenStack in the name of the service. > * Use module if it is consuming other services (such as heat). This may not be a great place to bring this up, but I don't really see how consuming other services makes heat/ceilometer a module. Most projects consume other services (they must use keystone at the barest minimum, trove uses nova, glance uses swift, etc) which would make darn near every service a module. It doesn't seem to be a valuable distinction, and I know that within the heat team, we say "service". Do operators, users, or developers find this distinction useful? Calling everything [blank] service seems like it'd be more consistent. -- Ryan Brown / Software Engineer, Openstack / Red Hat, Inc. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Should project name be uppercase or lowercase?
> > Forwarded Message > Subject:[openstack-dev] Should project name be uppercase or > lowercase? > Date: Tue, 7 Jul 2015 18:21:57 +0900 > From: Yuiko Takada > Reply-To: OpenStack Development Mailing List (not for usage > questions) > > To: OpenStack Development Mailing List (not for usage questions) > > > > > Hi folks, > > I found the difference between wiki[1] and governance[2]. > Yes, we are aware of the differences. I have asked the OpenStack Foundation legal counsel and they do not have a legal reason to capitalize project names. So, in documentation for consistency and to work on more valuable efforts, we need to stick to the established Documentation Conventions that have been in place since October 2013. https://wiki.openstack.org/wiki/Documentation/Conventions#Service_and_project_names > wiki says "Generally the capitalization of the project team names like > swift is lowercase." > But in governance, written as uppercase like "Nova", "Swift". > I don't believe a machine-readable YAML file indicates style or conventions for capitalization for a collection. Yes, I will be doing a patch for service names since it is a source of reference and if we think it will alleviate confusion I'll also lowercase the names of the projects in a separate patch. > How do you think which should we use uppercase vs lowercase for > representing project names? > I'll be patching the governance repo with some guidelines we have been using to make them official. The projects.yaml file is the reference point for the service catalog and documentation, and the doc team maintains a lookup list on the wiki page referenced above. Conventions for service names: - Uppercase first letter of first word only. - Do not use OpenStack in the name of the service. - Use module if it is consuming other services (such as heat). - Use service in general as that is mostly what is being added as projects. Conventions for project names: - In documentation published to docs.openstack.org, use lower case for project names except at the beginning of a sentence or heading title. (Note that all heading titles use sentence case for ease of learning capitalization rules.) - In the service catalog, use lower case. I hope this clarification helps. Please let me know if you have any questions or concerns. Thanks, Anne > > > [1]https://wiki.openstack.org/wiki/Documentation/Conventions > [2] > http://git.openstack.org/cgit/openstack/governance/tree/reference/projects.yaml > > > Best Regards, > Yuiko Takada > > > > -- > Christian Berendt > Cloud Solution Architect > Tel.: +49-171-5542175 > Mail: bere...@b1-systems.de > > B1 Systems GmbH > Osterfeldstraße 7 / 85088 Vohburg / http://www.b1-systems.de > GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537 > -- Anne Gentle Rackspace Principal Engineer www.justwriteclick.com __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Should project name be uppercase or lowercase?
On 7 July 2015 at 15:44, Jeremy Stanley wrote: > On 2015-07-07 13:24:00 +0100 (+0100), Dave Walker wrote: > [...] >> I am interested to hear why the convention in documentation for it to >> be lower case. > [...] > > Seems like this question comes up once for every two or three new > writers/editors who join the Docs effort. The most recent thread on > it is from last month. > > http://lists.openstack.org/pipermail/openstack-docs/2015-June/006796.html > > To summarize my understanding: > > 1. You should just avoid using project codenames in documentation, > in favor of official project names (e.g., use Compute rather > than nova) whenever possible. > > 2. There are concerns that capitalized use of project codenames > makes them more likely to present a high-profile/infringing > target for intellectual property (trademark, et cetera) claims. > I think it is probable that this question keeps coming back as the Documentation style guidelines do not provide the justification, which you summarised as above. I agree avoiding the use of code names where possible is entirely appropriate. However, when introducing a project in documentation, it seems agreeable to reference it such "OpenStack Block Storage (cinder)" and there onwards reference it as by the official title. However, the point on capitalisation of the code name seems crazy. Pretending a project name isn't a proper noun by adopting lower case seems odd. Was this really based on guidance from OpenStack legal team? -- Kind Regards, Dave Walker __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Should project name be uppercase or lowercase?
On 07/07/2015 04:44 PM, Jeremy Stanley wrote: On 2015-07-07 13:24:00 +0100 (+0100), Dave Walker wrote: [...] I am interested to hear why the convention in documentation for it to be lower case. [...] Seems like this question comes up once for every two or three new writers/editors who join the Docs effort. The most recent thread on it is from last month. http://lists.openstack.org/pipermail/openstack-docs/2015-June/006796.html To summarize my understanding: 1. You should just avoid using project codenames in documentation, in favor of official project names (e.g., use Compute rather than nova) whenever possible. With big tent we no longer have official names for every official project.. E.g. Ironic has also Ironic Python Agent (or ironic python agent?), Bifrost (or bifrost?) and Ironic Inspector (or ironic inspector?). 2. There are concerns that capitalized use of project codenames makes them more likely to present a high-profile/infringing target for intellectual property (trademark, et cetera) claims. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Should project name be uppercase or lowercase?
On 2015-07-07 13:24:00 +0100 (+0100), Dave Walker wrote: [...] > I am interested to hear why the convention in documentation for it to > be lower case. [...] Seems like this question comes up once for every two or three new writers/editors who join the Docs effort. The most recent thread on it is from last month. http://lists.openstack.org/pipermail/openstack-docs/2015-June/006796.html To summarize my understanding: 1. You should just avoid using project codenames in documentation, in favor of official project names (e.g., use Compute rather than nova) whenever possible. 2. There are concerns that capitalized use of project codenames makes them more likely to present a high-profile/infringing target for intellectual property (trademark, et cetera) claims. -- Jeremy Stanley __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Should project name be uppercase or lowercase?
Yuiko Takada wrote: How do you think which should we use uppercase vs lowercase for representing project names? They are proper names. The clear grammatical standard is capitalization. With that in mind, and unless there is some compelling reason for them not to be capitalized (I can't imagine there is one), we should follow that model and conform to the expected behavior. __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Should project name be uppercase or lowercase?
On 7 July 2015 at 13:11, Thierry Carrez wrote: > Yuiko Takada wrote: >> Hi folks, >> >> I found the difference between wiki[1] and governance[2]. >> wiki says "Generally the capitalization of the project team names like >> swift is lowercase." >> But in governance, written as uppercase like "Nova", "Swift". >> >> How do you think which should we use uppercase vs lowercase for >> representing project names? > > My personal take on it is that the project names (or the code > repositories) are lowercase: "nova", or "openstack/nova". > > The *project team* name is capitalized: "the Nova project team". > > I'm sure that Anne has a pretty strong position on that, though :) > This makes entire sense to me. I assumed that when used programmatically (or repositroy names) it should be in lowercase (unless a class name), when in prose it should be uppercase. For a recent documentation change, I put a project names capitalised which feels entirely appropriate as it is a proper noun. However, review requested that it followed documentation convention[0] of using lower case so I amended it to follow. I am interested to hear why the convention in documentation for it to be lower case. [0] https://wiki.openstack.org/wiki/Documentation/Conventions#Service_and_project_names -- Kind Regards, Dave Walker __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Should project name be uppercase or lowercase?
Yuiko Takada wrote: > Hi folks, > > I found the difference between wiki[1] and governance[2]. > wiki says "Generally the capitalization of the project team names like > swift is lowercase." > But in governance, written as uppercase like "Nova", "Swift". > > How do you think which should we use uppercase vs lowercase for > representing project names? My personal take on it is that the project names (or the code repositories) are lowercase: "nova", or "openstack/nova". The *project team* name is capitalized: "the Nova project team". I'm sure that Anne has a pretty strong position on that, though :) -- Thierry Carrez (ttx) __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
Re: [openstack-dev] Should project name be uppercase or lowercase?
On 07/07/2015 11:21 AM, Yuiko Takada wrote: Hi folks, I found the difference between wiki[1] and governance[2]. wiki says "Generally the capitalization of the project team names like swift is lowercase." But in governance, written as uppercase like "Nova", "Swift". It's grammatically incorrect (these are proper names and must be capitalized), but official policy is to lower case IIUC. How do you think which should we use uppercase vs lowercase for representing project names? [1]https://wiki.openstack.org/wiki/Documentation/Conventions [2]http://git.openstack.org/cgit/openstack/governance/tree/reference/projects.yaml Best Regards, Yuiko Takada __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
[openstack-dev] Should project name be uppercase or lowercase?
Hi folks, I found the difference between wiki[1] and governance[2]. wiki says "Generally the capitalization of the project team names like swift is lowercase." But in governance, written as uppercase like "Nova", "Swift". How do you think which should we use uppercase vs lowercase for representing project names? [1]https://wiki.openstack.org/wiki/Documentation/Conventions [2] http://git.openstack.org/cgit/openstack/governance/tree/reference/projects.yaml Best Regards, Yuiko Takada __ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
