Add improved developer experience and docs

README.org

@@ -1,93 +1,22 @@
-* verify-conformance-release
+* verify-conformance
+
+#+begin_quote
+a GitHub bot for verifying conformance submissions on github.com/cncf/k8s-conformance
+#+end_quote
 
 The behaviour of the bot is described here, in [[https://cucumber.io/docs/gherkin/][Gherkin]].  Each scenario is a requirement a PR must meet to qualify for conformance.
 
 Note: the line immediately beneath the scenario is the comment posted to the PR if the requirement is not met.
 
 See the feature scenarios, [[./kodata/features/verify-conformance-release.feature][in ./kodata/features]].
 
-* Build locally
-#+begin_src tmate :window prow-config
-ko build --local -B --tags latest .
-#+end_src
+* Developing
 
-* Set up local dev
-Log into GitHub regularly
-#+begin_src tmate :window prow-config
-unset GITHUB_TOKEN
-gh auth login
-#+end_src
-
-Update the oauth secret
-#+begin_src shell
-kubectl -n prow create secret generic prow-github-oauth \
-    --from-literal=oauth=$(yq e '."github.com".oauth_token' -P - < ~/.config/gh/hosts.yml) \
-    --dry-run=client -o yaml \
-    | kubectl apply -f -
-#+end_src
+build a container with
 
-#+RESULTS:
-#+begin_example
-secret/prow-github-oauth configured
-#+end_example
-
-Install the config
-#+begin_src shell
-kubectl -n prow create cm vcr-config --from-file=vcr.yaml=./hack/vcr.yaml --dry-run=client -o yaml | \
-    kubectl -n prow apply -f -
-#+end_src
-
-#+RESULTS:
-#+begin_example
-configmap/vcr-config created
-#+end_example
-
-Install the plugin
 #+begin_src tmate :window prow-config
-ko apply --local -B -f ./hack/verify-conformance-release-deployment-dev-temp.yaml -- -n prow
+ko build --local --base-import-paths .
 #+end_src
 
-#+RESULTS:
-#+begin_example
-deployment.apps/verify-conformance-release created
-#+end_example
-
-Read the logs
-#+begin_src tmate :window prow-config
-kubectl -n prow logs -l app=verify-conformance-release --tail=50 -f
-#+end_src
-
-Restart it
-#+begin_src tmate :window prow-config
-kubectl -n prow rollout restart deployment verify-conformance-release
-#+end_src
-
-#+RESULTS:
-#+begin_example
-deployment.apps/verify-conformance-release restarted
-#+end_example
-
-Uninstall the plugin
-#+begin_src shell
-kubectl -n prow delete -f ./hack/verify-conformance-release-deployment-dev-temp.yaml
-#+end_src
-
-#+RESULTS:
-#+begin_example
-deployment.apps "verify-conformance-release" deleted
-#+end_example
-
-* Run trial-implementation
-#+begin_src tmate :window trial-implementation
-cd ./cmd/trial-implementation
-go run .
-#+end_src
-
-* Running the plugin locally
-
-When run locally the plugin interacts with GitHub but by default does not make any changes
-if you want to apply changes to the PR inspected then you can pass in the flag, dry-run=false
+for more, read [[./docs/development.org][the development docs]].
 
-#+BEGIN_SRC shell
-./verify-conformance-release --hmac-secret-file=/home/ii/.secret-hook --github-token-path=/home/ii/.secret-oauth --plugin-config=./hack/vcr.yaml
-#+END_SRC

docs/development.org

@@ -0,0 +1,107 @@
+#+title: Development
+
+#+begin_quote
+Set up a local environment for development
+#+end_quote
+
+* Notes
+
+- currently pushes to a public container registry
+- the bot will log in and make comments are your GitHub user or whatever user the token belongs to
+
+* Environment
+
+install tools
+
+- [[https://podman.io][podman]] or [[https://docker.com][docker]]
+- [[https://ko.build][ko]]
+- [[https://kind.sigs.k8s.io][kind]]
+- [[https://kustomize.io][kustomize]]
+- [[https://kubernetes.io/docs/tasks/tools/#kubectl][kubectl]]
+- [[https://go.dev][go]]
+- [[https://cli.github.com/][gh]]
+
+#+begin_src shell :results silent
+brew install podman ko kind kustomize kubectl go gh
+#+end_src
+
+log in to GitHub with ~gh~
+
+#+begin_src shell: results silent
+gh auth login -s write:packages
+#+end_src
+
+log into ghcr.io
+
+#+begin_src shell :results silent
+gh auth token | ko login ghcr.io --username "$(gh api user --jq .login)" --password-stdin
+#+end_src
+
+create a cluster
+
+#+begin_src shell :results silent
+kind create cluster
+#+end_src
+
+build image
+
+#+begin_src shell :results silent
+export KO_DOCKER_REPO=ghcr.io/cncf-infra/verify-conformance
+IMAGE="$(ko build --base-import-paths .)"
+#+end_src
+(*NOTE*: feel free to swap out registry above)
+
+configure components
+
+#+begin_src shell :results silent
+cd ./hack/local-dev/
+kustomize edit set image ko://cncf.io/infra/verify-conformance-release="$IMAGE"
+#+end_src
+(*NOTE*: avoid committing this change)
+
+write secrets (*example*)
+
+#+begin_src shell :results silent
+mkdir -p ./tmp/
+echo "$(openssl rand -base64 15)" > ./tmp/hmac
+gh auth token > ./tmp/token
+#+end_src
+(*NOTE*: avoid committing these values)
+
+apply
+
+#+begin_src shell :results silent
+kustomize build . | kubectl apply -f -
+#+end_src
+
+observe resources
+
+#+begin_src shell :results silent
+kubectl -n prow get all
+#+end_src
+
+teardown
+
+#+begin_src shell :results silent
+kind delete cluster
+#+end_src
+
+* Tips
+
+read the logs
+
+#+begin_src shell :results silent
+kubectl -n prow logs -l app=verify-conformance-release --tail=50 -f
+#+end_src
+
+restart it
+
+#+begin_src shell :results silent
+kubectl -n prow rollout restart deployment verify-conformance-release
+#+end_src
+
+compile test
+
+#+begin_src shell
+go build -o bin/ .
+#+end_src

hack/local-dev/ghproxy.yaml

@@ -0,0 +1,71 @@
+---
+kind: PersistentVolumeClaim
+apiVersion: v1
+metadata:
+  namespace: prow
+  labels:
+    app: ghproxy
+  name: ghproxy
+spec:
+  accessModes:
+    - ReadWriteOnce
+  resources:
+    requests:
+      storage: 100Gi
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  namespace: prow
+  name: ghproxy
+  labels:
+    app: ghproxy
+spec:
+  selector:
+    matchLabels:
+      app: ghproxy
+  replicas: 1
+  template:
+    metadata:
+      labels:
+        app: ghproxy
+    spec:
+      containers:
+      - name: ghproxy
+        image: gcr.io/k8s-prow/ghproxy:v20240515-dd5d0eeaa
+        args:
+        - --cache-dir=/cache
+        - --cache-sizeGB=99
+        - --push-gateway=pushgateway
+        - --serve-metrics=true
+        ports:
+        - name: main
+          containerPort: 8888
+        - name: metrics
+          containerPort: 9090
+        volumeMounts:
+        - name: cache
+          mountPath: /cache
+      volumes:
+      - name: cache
+        persistentVolumeClaim:
+          claimName: ghproxy
+---
+apiVersion: v1
+kind: Service
+metadata:
+  labels:
+    app: ghproxy
+  namespace: prow
+  name: ghproxy
+spec:
+  ports:
+  - name: main
+    port: 80
+    protocol: TCP
+    targetPort: 8888
+  - name: metrics
+    port: 9090
+  selector:
+    app: ghproxy
+  type: ClusterIP

hack/local-dev/kustomization.yaml

@@ -0,0 +1,34 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+resources:
+- ./namespace.yaml
+- ../../config/default
+- ./ghproxy.yaml
+patches:
+  - path: ./verify-conformance-patch.yaml
+namespace: prow
+generatorOptions:
+  disableNameSuffixHash: true
+configMapGenerator:
+- behavior: replace
+  files:
+  - ./vcr.yaml
+  name: vcr-config
+  namespace: prow
+- files:
+  - ./plugins.yaml
+  name: plugins
+  namespace: prow
+secretGenerator:
+- files:
+  - token=./tmp/token
+  name: github-token
+  namespace: prow
+- files:
+  - hmac=./tmp/hmac
+  name: hmac-token
+  namespace: prow
+images:
+- digest: sha256:7db60baff20817a23d3c141fb4984ccfd84cda7eabadb81400fabeaae251a05e
+  name: ko://cncf.io/infra/verify-conformance-release
+  newName: ghcr.io/cncf-infra/verify-conformance/verify-conformance-release

hack/local-dev/namespace.yaml

@@ -0,0 +1,5 @@
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: prow

hack/local-dev/plugins.yaml

@@ -0,0 +1,17 @@
+plugins:
+  cncf-infra:
+    plugins:
+    - approve
+    - assign
+    - blunderbuss
+    - cat
+    - dog
+    - help
+    - heart
+    - hold
+    - label
+    - lgtm
+    - trigger
+    - verify-owners
+    - wip
+    - yuks

hack/local-dev/vcr.yaml

@@ -0,0 +1,6 @@
+external_plugins:
+  cncf-infra/k8s-conformance:
+  - name: verify-conformance-release
+    events:
+      - issue_comment
+      - pull_request

hack/local-dev/verify-conformance-patch.yaml

@@ -0,0 +1,20 @@
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: verify-conformance-release
+  namespace: prow
+spec:
+  template:
+    spec:
+      containers:
+        - name: verify-conformance-release
+          args:
+            - --github-endpoint=http://ghproxy
+            - --github-endpoint=https://api.github.com
+            - --dry-run=false
+            - --hmac-secret-file=/etc/webhook/hmac
+            - --plugin-config=/plugin/vcr.yaml
+            - --update-period=5m
+            - --github-token-path=/etc/github/token
+          env: