From 152aeba9f0bf207040e3f61aab425739dfae5891 Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Thu, 14 Nov 2019 16:20:46 -0500 Subject: [PATCH 1/3] update style guide for styling component names - Attempt to outline style conventions for components and component tools - Interested in comments and feedback --- .../en/docs/contribute/style/style-guide.md | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/content/en/docs/contribute/style/style-guide.md b/content/en/docs/contribute/style/style-guide.md index 5f92636c5f579..d2597086b3068 100644 --- a/content/en/docs/contribute/style/style-guide.md +++ b/content/en/docs/contribute/style/style-guide.md @@ -146,6 +146,33 @@ Set the value of the `replicas` field in the configuration file. | Set the value The value of the `exec` field is an ExecAction object. | The value of the "exec" field is an ExecAction object. {{< /table >}} +### Use code style for Kubernetes command tool and component names + +{{< table caption = "Do and Don't - Use code style for Kubernetes command tool and component names" >}} +Do | Don't +:--| :----- +The `kubelet` preserves node stability. | The kubelet preserves node stability. +The `kube-proxy` maintains network rules on nodes. | The kube-proxy maintains network rules on nodes. +Kubectl handles locating and authenticating to the API server. | `kubectl` handles locating and authenticating to the apiserver. +{{< /table >}} + +### Starting a sentence with a component tool or component name + +{{< table caption = "Do and Don't - Starting a sentence with a component tool or component name" >}} +Do | Don't +:--| :----- +The `kube-apiserver` is designed to scale horizontally. | `kube-apiserver` is designed to scale horizontally. +Kubectl handles locating and authenticating to the API server. | The Kubectl handles locating and authenticating to the apiserver. +{{< /table >}} + +### Use a general descriptor over a specific component name + +{{< table caption = "Do and Don't - Use a general descriptor over a specific component name" >}} +Do | Don't +:--| :----- +The Kubernetes API server offers an OpenAPI spec. | The apiserver offers an OpenAPI spec. +{{< /table >}} + ### Use normal style for string and integer field values For field values of type string or integer, use normal style without quotation marks. From 0e161deedf34049f30610129a5877d1907e00522 Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Mon, 18 Nov 2019 09:33:18 -0500 Subject: [PATCH 2/3] update style examples --- content/en/docs/contribute/style/style-guide.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/en/docs/contribute/style/style-guide.md b/content/en/docs/contribute/style/style-guide.md index d2597086b3068..6fa5f1731eee7 100644 --- a/content/en/docs/contribute/style/style-guide.md +++ b/content/en/docs/contribute/style/style-guide.md @@ -152,8 +152,7 @@ The value of the `exec` field is an ExecAction object. | The value of the "exec" Do | Don't :--| :----- The `kubelet` preserves node stability. | The kubelet preserves node stability. -The `kube-proxy` maintains network rules on nodes. | The kube-proxy maintains network rules on nodes. -Kubectl handles locating and authenticating to the API server. | `kubectl` handles locating and authenticating to the apiserver. +The `kubectl` handles locating and authenticating to the API server. | The kubectl handles locating and authenticating to the apiserver. {{< /table >}} ### Starting a sentence with a component tool or component name @@ -161,16 +160,17 @@ Kubectl handles locating and authenticating to the API server. | `kubectl` handl {{< table caption = "Do and Don't - Starting a sentence with a component tool or component name" >}} Do | Don't :--| :----- -The `kube-apiserver` is designed to scale horizontally. | `kube-apiserver` is designed to scale horizontally. -Kubectl handles locating and authenticating to the API server. | The Kubectl handles locating and authenticating to the apiserver. +The `kubeadm` tool bootstraps and provisions machines in a cluster. | `kubeadm` tool bootstraps and provisions machines in a cluster. +The `kube-scheduler` is the default scheduler for Kubernetes. | kube-scheduler is the default scheduler for Kubernetes. {{< /table >}} -### Use a general descriptor over a specific component name +### Use a general descriptor over a component name -{{< table caption = "Do and Don't - Use a general descriptor over a specific component name" >}} +{{< table caption = "Do and Don't - Use a general descriptor over a component name" >}} Do | Don't :--| :----- The Kubernetes API server offers an OpenAPI spec. | The apiserver offers an OpenAPI spec. +Aggregated APIs are subordinate API servers. | Aggregated APIs are subordinate APIServers. {{< /table >}} ### Use normal style for string and integer field values From 040b1a269ff428bfaa1a85492f9adf0542b34d78 Mon Sep 17 00:00:00 2001 From: Karen Bradshaw Date: Tue, 19 Nov 2019 10:17:38 -0500 Subject: [PATCH 3/3] style edits - removed code style for components not cmd tools - added style suggestion for namespaces - cleaned up a few stray spaces --- content/en/docs/contribute/style/style-guide.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/content/en/docs/contribute/style/style-guide.md b/content/en/docs/contribute/style/style-guide.md index 6fa5f1731eee7..30865c49e8ef3 100644 --- a/content/en/docs/contribute/style/style-guide.md +++ b/content/en/docs/contribute/style/style-guide.md @@ -111,7 +111,7 @@ Open the `/_data/concepts.yaml` file. | Open the /_data/concepts.yaml file. Do | Don't :--| :----- events are recorded with an associated "stage". | events are recorded with an associated "stage." -The copy is called a "fork". | The copy is called a "fork." +The copy is called a "fork". | The copy is called a "fork." {{< /table >}} ## Inline code formatting @@ -133,17 +133,18 @@ Use meaningful variable names that have a context. | Use variable names such as Remove trailing spaces in the code. | Add trailing spaces in the code, where these are important, because the screen reader will read out the spaces as well. {{< /table >}} -{{< note >}} +{{< note >}} The website supports syntax highlighting for code samples, but specifying a language is optional. Syntax highlighting in the code block should conform to the [contrast guidelines.](https://www.w3.org/WAI/WCAG21/quickref/?versions=2.0&showtechniques=141%2C143#contrast-minimum) {{< /note >}} -### Use code style for object field names +### Use code style for object field names and namespaces {{< table caption = "Do and Don't - Use code style for object field names" >}} Do | Don't :--| :----- Set the value of the `replicas` field in the configuration file. | Set the value of the "replicas" field in the configuration file. The value of the `exec` field is an ExecAction object. | The value of the "exec" field is an ExecAction object. +Run the process as a Daemonset in the `kube-system` namespace. | Run the process as a Daemonset in the kube-system namespace. {{< /table >}} ### Use code style for Kubernetes command tool and component names @@ -151,8 +152,9 @@ The value of the `exec` field is an ExecAction object. | The value of the "exec" {{< table caption = "Do and Don't - Use code style for Kubernetes command tool and component names" >}} Do | Don't :--| :----- -The `kubelet` preserves node stability. | The kubelet preserves node stability. +The kubelet preserves node stability. | The `kubelet` preserves node stability. The `kubectl` handles locating and authenticating to the API server. | The kubectl handles locating and authenticating to the apiserver. +Run the process with the certificate, `kube-apiserver --client-ca-file=FILENAME`. | Run the process with the certificate, kube-apiserver --client-ca-file=FILENAME. | {{< /table >}} ### Starting a sentence with a component tool or component name @@ -161,7 +163,7 @@ The `kubectl` handles locating and authenticating to the API server. | The kubec Do | Don't :--| :----- The `kubeadm` tool bootstraps and provisions machines in a cluster. | `kubeadm` tool bootstraps and provisions machines in a cluster. -The `kube-scheduler` is the default scheduler for Kubernetes. | kube-scheduler is the default scheduler for Kubernetes. +The kube-scheduler is the default scheduler for Kubernetes. | kube-scheduler is the default scheduler for Kubernetes. {{< /table >}} ### Use a general descriptor over a component name