From fae48094d8412a779728710e95fc40f6510678da Mon Sep 17 00:00:00 2001
From: Chip Zoller <chipzoller@gmail.com>
Date: Mon, 12 Apr 2021 21:00:29 -0400
Subject: [PATCH] add PR docs guide (#1788)

Signed-off-by: Chip Zoller <chipzoller@gmail.com>
---
 .github/PULL_REQUEST_TEMPLATE.md |  34 ++++++--
 .github/pr_documentation.md      | 141 +++++++++++++++++++++++++++++++
 2 files changed, 169 insertions(+), 6 deletions(-)
 create mode 100644 .github/pr_documentation.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 6ee9864815..f1eccf20a6 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -14,7 +14,7 @@ You can discuss changes with maintainers in the [Kyverno Slack Channel](https://
 
 <!--
 
-> Uncomment only one ` /kind <>` line, hit enter to put that in a new line, and remove leading whitespaces from that line:
+> Uncomment only one ` /kind <>` line, hit enter to put that in a new line, and remove leading white spaces from that line:
 >
 > /kind api-change
 > /kind bug
@@ -25,10 +25,28 @@ You can discuss changes with maintainers in the [Kyverno Slack Channel](https://
 > /kind feature
 -->
 
-## Proposed changes
+## Proposed Changes
 
 <!--
-Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.
+Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request. 
+
+***NOTE***: If this PR results in new or altered behavior which is user facing, you **MUST** read and follow the steps outlined in the [PR documentation guide](pr_documentation.md) and add Proof Manifests as defined below.
+-->
+
+### Proof Manifests
+
+<!--
+Read and follow the [PR documentation guide](pr_documentation.md) for more details first. This section is for pasting your YAML manifests (Kubernetes resources and Kyverno policies) which allow maintainers to prove the intended functionality is achieved by your PR. Please use proper fenced code block formatting, for example:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: roles-dictionary
+  namespace: default
+data:
+  allowed-roles: "[\"cluster-admin\", \"cluster-operator\", \"tenant-admin\"]"
+```
 -->
 
 ## Checklist
@@ -40,12 +58,16 @@ them, don't hesitate to ask. We're here to help! This is simply a reminder of wh
 
 - [] I have read the [contributing guidelines](https://github.com/kyverno/kyverno/blob/main/CONTRIBUTING.md).
 - [] I have added tests that prove my fix is effective or that my feature works.
-- [] I have added or changed [the documentation](https://github.com/kyverno/website).
-  - If not, I have raised an issue in [kyverno/website](https://github.com/kyverno/website) to track the doc update:
+- [] My PR contains new or altered behavior to Kyverno and
+  - [] I have added or changed [the documentation](https://github.com/kyverno/website) myself in an existing PR and the link is:
+  <!-- Uncomment to link to the PR -->
+  <!-- https://github.com/kyverno/website/pull/123 -->
+  - [] I have raised an issue in [kyverno/website](https://github.com/kyverno/website) to track the doc update and the link is:
   <!-- Uncomment to link to the issue -->
   <!-- https://github.com/kyverno/website/issues/1 -->
+  - [] I have read the [PR documentation guide](pr_documentation.md) and followed the process including adding proof manifests to this PR.
 
-## Further comments
+## Further Comments
 
 <!--
 If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution
diff --git a/.github/pr_documentation.md b/.github/pr_documentation.md
new file mode 100644
index 0000000000..406b97bfb6
--- /dev/null
+++ b/.github/pr_documentation.md
@@ -0,0 +1,141 @@
+## PR Documentation
+
+In order to assist the Kyverno maintainers of both the software and documentation as well as to provide clarity to PR reviewers, any PRs which result in new or different behavior exposed to users must be captured in the documentation. In order to ensure these changes do not fall by the wayside, follow this guide if your PR results in new or changed behavior to Kyverno which impacts users. Examples of changes which fall under this definition:
+
+* Adding a command or flags to the Kyverno CLI
+* Adding API lookup capabilities
+* Changing schema definitions
+* Adding multi-line YAML lookups
+* Other functionality that users can "touch"
+
+Examples of changes which are exempt:
+
+* Bug fixes
+* Logging level or message changes
+* Test cases
+* Other changes which are internal to the code base
+
+If you are unsure what type your PR falls under, please either start a thread on the [Kyverno Slack channel](https://kubernetes.slack.com/) or a [discussion](https://github.com/kyverno/kyverno/discussions).
+
+## Story Process
+
+If your PR does result in new or altered behavior, under the Proposed Changes section of the PR, please describe the following:
+
+1. What was Kyverno's behavior before your PR
+2. What does this PR do
+3. What is the resulting behavior after your PR
+
+### Example
+
+1. Prior to this PR, ConfigMaps had to be created with JSON-encoded data such as:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: roles-dictionary
+  namespace: default
+data:
+  allowed-roles: "[\"cluster-admin\", \"cluster-operator\", \"tenant-admin\"]"
+```
+
+2. This PR adds the ability to specify string array values in ConfigMap resources as multi-line YAML (block scalars) as opposed to JSON-encoded data.
+
+3. After this PR, ConfigMaps can now be created as follows:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+    name: roles-dictionary
+    namespace: default
+data:
+  allowed-roles: |-
+    cluster-admin
+    cluster-operator
+    tenant-admin
+```
+
+## Proof Manifests
+
+To assist the docs maintainers in updating the documentation (if you have not done so yourself) and code maintainers/community to quickly understand and test your PR, please provide YAML manifests which help them "prove" your changes.
+
+### Example
+
+To test this PR's behavior, create `cm.yaml`:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: animals
+  namespace: default
+data:
+  animals: |-
+    snake
+    bear
+    cat
+    dog
+```
+
+Create `cpol.yaml`:
+
+```yaml
+apiVersion: kyverno.io/v1
+kind: ClusterPolicy
+metadata:
+  name: cm-array-example
+spec:
+  validationFailureAction: enforce
+  background: false
+  rules:
+  - name: validate-role-annotation
+    context:
+      - name: animals
+        configMap:
+          name: animals
+          namespace: default
+    match:
+      resources:
+        kinds:
+        - Deployment
+    validate:
+      message: "The animal {{ request.object.metadata.labels.animal }} is not in the allowed list of animals: {{ animals.data.animals }}."
+      deny:
+        conditions:
+        - key: "{{ request.object.metadata.labels.animal }}"
+          operator: NotIn
+          value:  "{{ animals.data.animals }}"
+```
+
+Create `deploy.yaml`
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: busybox
+  labels:
+    app: busybox
+    color: red
+    animal: cow
+    food: pizza
+    car: jeep
+    env: qa
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: busybox
+  template:
+    metadata:
+      labels:
+        app: busybox
+    spec:
+      containers:
+      - image: busybox:1.28
+        name: busybox
+        command: ["sleep", "9999"]
+```
+
+See that the Deployment fails now that Kyverno can read from multi-line YAML strings in a ConfigMap.