Merge pull request #38812 from jboxman-rh/update-guidelines-for-yaml

Update guidelines with YAML formatting

Author: jab-rh

contributing_to_docs/doc_guidelines.adoc

@@ -978,8 +978,7 @@ $ oc get endpoints --all-namespaces --template \
 # subscription-manager list
 ----
 
-* For snippets or sections of a larger file, use an ellipsis (`...`) to show that
-the file continues before and/or after the quoted block:
+* For snippets or sections of a file, use an ellipsis (`...`) to show that the file continues before and/or after the quoted block.
 +
 ----
 apiVersion: v1
@@ -993,11 +992,10 @@ metadata:
 or
 +
 ----
+Name:               ci-ln-iyhx092-f76d1-nvdfm-worker-b-wln2l
+Roles:              worker
 ...
-spec:
-  containers:
-  - args:
-    image: k8s.gcr.io/liveness
+Taints:             node-role.kubernetes.io/infra:NoSchedule
 ...
 ----
 +
@@ -1017,6 +1015,127 @@ can be updated to use `jsonpath` instead:
 $ oc get clusterversion -o jsonpath='{.items[0].spec}{"\n"}'
 ----
 
+* For Bash "here" documents use `[source,terminal]`, such as the following example:
++
+....
+[source,terminal]
+----
+$ cat <<EOF| oc create -f -
+apiVersion: v1
+kind: Pod
+metadata:
+  name: mlistener
+  labels:
+    app: multicast-verify
+EOF
+----
+....
+
+* For the output of commands use `[source,text]`, such as with the following example output from the `oc describe <pural> <object>` command:
++
+....
+[source,text]
+----
+Name:               node1.example.com
+Roles:              worker
+Labels:             beta.kubernetes.io/arch=amd64
+...
+Annotations:        cluster.k8s.io/machine: openshift-machine-api/ahardin-worker-us-east-2a-q5dzc
+...
+CreationTimestamp:  Wed, 13 Feb 2019 11:05:57 -0500
+----
+....
+
+=== YAML formatting for Kubernetes and OpenShift API objects
+The following formatting guidelines apply to YAML manifests, but do not apply to the installation configuration YAML specified by `install-config.yaml`.
+
+When possible, ensure that YAML is valid in a running cluster. You can validate YAML with `oc apply` with the following invocation:
+
+----
+$ oc apply -f test.yaml --dry-run=client
+----
+
+==== Required fields
+
+- Include the `apiVersion` and `kind` so that a user always knows the context of the YAML.
+- Include the full hierarchy to a deeply nested key.
+- For objects that are in the global scope, such as for `config.openshift.io` API group, always include the `metadata.name` for the object, which is usually `cluster`.
+
+.Example API object in the global scope
+----
+apiVersion: config.openshift.io/v1
+kind: Scheduler
+metadata:
+  name: cluster
+...
+spec:
+  defaultNodeSelector: node-role.kubernetes.io/app=
+...
+----
+
+.Example deeply nested key with full context for `.ports` array
+----
+apiVersion: v1
+kind: Pod
+metadata:
+  name: pod1
+  namespace: default
+spec:
+  containers:
+  - name: web
+    image: nginx
+    ports:
+    - name: web
+      containerPort: 80
+      protocol: TCP
+----
+
+==== Formatting
+Use the following conventions govern the layout of YAML for API objects.
+
+- Begin YAML at the beginning of the left margin.
+- Use two-space indentation.
+- Indent arrays at the same depth as the parent field.
+- Include a space immediately after the colon for keys.
+- Use block style for complex strings, such as embedded JSON or text blocks. You can enable block style by specifying `|` or `|-` after a field and indenting the field content by two spaces, such as in the following example:
++
+----
+fieldName: |-
+  This is a string.
+  And it can be on multiple lines.
+----
+- When truncating YAML, always precede an ellipsis with a pound so that the YAML is valid.
+
+.Example with array indentation flush with parent field
+----
+apiVersion: v1
+kind: Pod
+metadata:
+  name: pod1
+  labels:
+  - key1: val1
+  - key2: val2
+spec:
+...
+----
+
+.Example with block string for annotation
+----
+apiVersion: v1
+kind: Pod
+metadata:
+  name: pod1
+  annotations:
+    k8s.v1.cni.cncf.io/networks: |-
+      [
+        {
+          "name": "net"
+        }
+      ]
+spec:
+...
+----
+
 === Inline code or commands
 Do NOT show full commands or command syntax inline within a sentence. The next section covers how to show commands and command syntax.