On Thu, Jun 25, 2015 at 5:17 AM, Andreas Jaeger <aj@xxxxxxxx
<mailto:aj@xxxxxxxx>> wrote:
On 06/25/2015 12:04 PM, Steve Gordon wrote:
----- Original Message -----
From: "Andreas Jaeger" <aj@xxxxxxxx <mailto:aj@xxxxxxxx>>
To: "Lana Brindley" <openstack@xxxxxxxxxxxxxxxx
<mailto:openstack@xxxxxxxxxxxxxxxx>>,
openstack-doc-core@xxxxxxxxxxxxxxxxxxx
<mailto:openstack-doc-core@xxxxxxxxxxxxxxxxxxx>
On 06/25/2015 02:16 AM, Lana Brindley wrote:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
Hi everyone,
First of all, I'm sorry that the Ironic docs thing has
turned into a bit
of a disaster. I had no idea that we were going to end
up in a standards
argument over this, but I'm still hopeful that we can
see a path through
this.
The problem: A number of patches (mostly created by
Shilla, if I'm not
mistaken) are now being blocked in the Ironic repo by an
Ironic core who
doesn't agree with our standards. While they're
certainly entitled to
question our standards, blocking the patches means that
other good work
is not getting merged.
The solution: I'm not certain. Right now, what I want to
do is send
email to Devananda (the Ironic PTL) with a list of the
patches being
blocked, so we can determine if there's a way we can
appease the Ironic
core team's concerns over standards. Shilla (and others
who have a patch
out on this), can you please send me a list of the
patches currently
being blocked?
The fallout: We're already arguing about the standard in
question on our
own list, and the community seems deeply divided. I
personally don't
care about the capitalisation of service names, and am
happy to enforce
whatever the community decides. That said, I feel as
though the
community is unlikely to come to a solid conclusion on
this. Do cores
have an opinion? If there is a strong tendency amongst
this group,
perhaps it's easier to just go with that and adjust
accordingly. Please
feel free to debate this topic on this thread.
So, this is "Ironic" vs "ironic"?
I think what needs to be worked out with a project is that our
conventions are enforced if we work together. Like there are
hacking
rules for code which a core team reviews, there are
documentation rules
that are under the Documentation team (btw. going to a
reviewed style
guide would help with the story;)!
On the Ironic vs ironic: While I prefer the lower-case, I
see upper-case
everywhere.
It's the number one change that I request during reviews.
If we want to enforce our documentation style everywhere, it
might be
better to not enforce the capitalization or change the rule.
So, I'm willing to change my vote if that is needed to adopt
the Doc
style everywhere ;)
Anne, is the Doc style adoption a TC discussion?
What do we need to make our style guide better consumable by
other projects?
Andreas
This is the patch in question:
https://review.openstack.org/#/c/194230/1/reference/projects.yaml
It's about Bare metal service versus Bare Metal service.
Thanks!
Ah, that one ;(
So, it's "Bare metal service" vs "Bare Metal service" vs "Bare Metal
Service".
We did a couple of consistency changes there and might need to go -
as mentioned in the review - over the complete list to have
consistency. And that discussion we need to have and I think Docs
should have final say on it - but up for the TC,
Yes, it is up to the TC but they certainly want docs team input. I've
put my input on the patch itself:
---
For context: we are in this situation because of legal names, where some
of the original governance allowed projects to use "OpenStack" in the
docs as part of their name very early on. So, sometimes the phrasing
needed "service" to help with readability. Also, legally we were
required to use module due to branding with the OpenStack name.
So, the convention is:
* 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.
Now that we have the interop and brand guidelines, the use of OpenStack
in a name in the docs is not needed, but we still need to be very
careful and considerate in naming consistently.
Bare metal fits our first naming rule.
Changing these back and forth is not helpful. I will better document the
naming conventions in the governance repo to avoid this in the future.
---
But here's what I really want to say. To be high-value contributors to
all the projects we must avoid the reputation of being nit pickers.
