diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/best_practices_guide.adoc | 10 | ||||
| -rw-r--r-- | docs/core_concepts_guide.adoc | 4 | ||||
| -rw-r--r-- | docs/style_guide.adoc | 6 |
3 files changed, 10 insertions, 10 deletions
diff --git a/docs/best_practices_guide.adoc b/docs/best_practices_guide.adoc index 938b6b46a..a839cd203 100644 --- a/docs/best_practices_guide.adoc +++ b/docs/best_practices_guide.adoc @@ -29,7 +29,7 @@ Our tooling is flexible enough that exceptions can be made so that the tool the == Python === PyLint -We use http://www.pylint.org/[PyLint] in an attempt to keep our python code as clean and as managable as possible. Our build bot runs each pull request through PyLint and any warnings or errors cause the build bot to fail the pull request. +http://www.pylint.org/[PyLint] is used in an attempt to keep our python code as clean and as managable as possible. Our build bot runs each pull request through PyLint and any warnings or errors cause the build bot to fail the pull request. ''' [cols="2v,v"] @@ -49,7 +49,7 @@ Instead, http://docs.pylint.org/faq.html#is-it-possible-to-locally-disable-a-par .Exceptions: 1. When PyLint fails because of a dependency that can't be installed on the build bot -1. When PyLint fails because we are including a module that is outside of our control (like Ansible) +1. When PyLint fails because of including a module that is outside of our control (like Ansible) ''' [cols="2v,v"] @@ -70,7 +70,7 @@ The purpose of this rule is to inform future developers about the disable. # Reason: disable pylint maybe-no-member because overloaded use of # the module name causes pylint to not detect that 'results' # is an array or hash -# Status: permanently disabled unless we can find a way to fix this. +# Status: permanently disabled unless a way is found to fix this. # pylint: disable=maybe-no-member metadata[line] = results.pop() ---- @@ -92,7 +92,7 @@ metadata[line] = results.pop() When using the jinja2 `default` filter, unless the variable is a boolean, specify `true` as the second parameter. This will cause the default filter to replace empty strings, lists, etc with the provided default. -This is because we would prefer to either have a sane default set than to have an empty string, list, etc. We don't, for example, want config values set to an empty string. +This is because it is preferable to either have a sane default set than to have an empty string, list, etc. For example, it is preferable to have a config value set to a sane default than to have it simply set as an empty string. .From the http://jinja.pocoo.org/docs/dev/templates/[Jinja2 Docs]: [quote] @@ -119,4 +119,4 @@ If you want to use default with variables that evaluate to false you have to set In other words, normally the `default` filter will only replace the value if it's undefined. By setting the second parameter to `true`, it will also replace the value if it defaults to a false value in python, so None, empty list, empty string, etc. -We almost always want this instead of the empty list, string, etc. +This is almost always more desirable than an empty list, string, etc. diff --git a/docs/core_concepts_guide.adoc b/docs/core_concepts_guide.adoc index 0d746bfb5..fa2421eec 100644 --- a/docs/core_concepts_guide.adoc +++ b/docs/core_concepts_guide.adoc @@ -7,9 +7,9 @@ The purpose of this guide is to describe core concepts used in this repository. It is important to note that this repository may not currently implement all of the concepts, but our intention is that it will. == Logical Grouping Concepts -The following are the concepts we use to logically group OpenShift cluster instances. +The following are the concepts used to logically group OpenShift cluster instances. -We use these groupings to perform operations specifically against instances in the specified group. +These groupings are used to perform operations specifically against instances in the specified group. For example, run an Ansible playbook against all instances in the `production` environment, or run an adhoc command against all instances in the `acme-corp` cluster group. diff --git a/docs/style_guide.adoc b/docs/style_guide.adoc index 714b56c70..b4c99e1d9 100644 --- a/docs/style_guide.adoc +++ b/docs/style_guide.adoc @@ -13,7 +13,7 @@ This style guide complies with https://www.ietf.org/rfc/rfc2119.txt[RFC2119]. == Ansible Variable Naming === Global Variables -We define Ansible global variables as any variables outside of ansible roles. Examples include playbook variables, variables passed in on the cli, etc. +Ansible global variables are defined as any variables outside of ansible roles. Examples include playbook variables, variables passed in on the cli, etc. ''' [cols="2v,v"] @@ -30,7 +30,7 @@ g_environment: someval ---- ==== Role Variables -We define Ansible role variables as variables contained in (or passed into) a role. +Ansible role variables are defined as variables contained in (or passed into) a role. ''' [cols="2v,v"] @@ -104,4 +104,4 @@ Even though both roles have the same prefix (mur), and even though both roles ha This would only be a problem if my_uber_role depended on made_up_role, or vice versa. Or if either of these two roles included things from the other. -We think this is enough of a corner case that it is unlikely to happen. If it does, we will address it on a case by case basis. +This is enough of a corner case that it is unlikely to happen. If it does, it will be addressed on a case by case basis. |