OTA-560: Improve developer-oriented docs

CONTRIBUTING.md

@@ -22,20 +22,18 @@ For contributors who want to work up pull requests, the workflow is roughly:
 1. Create a topic branch from where you want to base your work (usually master).
 2. Make commits of logical units.
 3. Make sure your commit messages are in the proper format (see [below](#commit-message-format)).
-4. If necessary, you may use `make update-codegen` to update generated code.
-5. Make sure the tests pass (`go test ./...`), and add any new tests as appropriate.
+4. Make sure your [code builds][build-cvo] and follows the [coding style](#coding-style)
+5. Make sure the [tests pass][test-cvo] and add any new tests as appropriate.
 6. Push your changes to a topic branch in your fork of the repository.
 7. Submit a pull request to the original repository.
-8. The [repo owners](OWNERS) will respond to your issue promptly, following [the ususal Prow workflow][prow-review].
+8. The [repo owners](OWNERS) will respond to your issue promptly, following [the usual Prow workflow][prow-review].
 
 Thanks for your contributions!
 
 ## Coding Style
 
-The coding style suggested by the Golang community is used in installer.
-See the [style doc][golang-style] for details.
-Please follow them when working on your contributions.
-You may also `go fmt ./...` to have Go automatically format your .
+The Cluster Version Operator follows the common Golang [coding style][golang-style]. Please follow them when working
+on your contributions. Use `go fmt ./...` to format your code.
 
 ## Commit Message Format
 
@@ -68,3 +66,5 @@ This allows the message to be easier to read on GitHub as well as in various Git
 [new-issue]: https://github.com/openshift/cluster-version-operator/issues/new
 [prow-review]: https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md#the-code-review-process
 [security]: https://access.redhat.com/security/team/contact
+[build-cvo]: ./docs/dev/README.md#building-cvo
+[test-cvo]: ./docs/dev/README.md#testing-cvo

Makefile

@@ -11,16 +11,15 @@ test:
 	go test ./...
 .PHONY: test
 
+integration-test:
+	./hack/integration-test.sh
+.PHONY: integration-test
+
+format:
+	go fmt ./...
+.PHONY: format
+
 clean:
 	rm -rf _output/
 	rm -rf bin
 .PHONY: clean
-
-update-codegen-crds:
-	go run ./vendor/github.com/openshift/library-go/cmd/crd-schema-gen/main.go --domain openshift.io --apis-dir vendor/github.com/openshift/api --manifests-dir install/
-update-codegen: update-codegen-crds
-verify-codegen-crds:
-	go run ./vendor/github.com/openshift/library-go/cmd/crd-schema-gen/main.go --domain openshift.io --apis-dir vendor/github.com/openshift/api --manifests-dir install/ --verify-only
-verify-codegen: verify-codegen-crds
-verify: verify-codegen
-.PHONY: update-codegen-crds update-codegen verify-codegen-crds verify-codegen verify

docs/dev/README.md

@@ -1,4 +1,90 @@
-# Permanently Moved
+# Developing Cluster Version Operator
 
-Other than run-cvo-locally.md, all other documents have moved to [openshift/enhancements](https://github.com/openshift/enhancements/tree/master/dev-guide/cluster-version-operator).
+> :warning: This document only covers the basic development, building and testing tasks. For information about
+> concepts used and implemented in CVO, please see the
+> [dev-guide in the openshift/enhancements repository](https://github.com/openshift/enhancements/tree/master/dev-guide/cluster-version-operator).
 
+## Building CVO
+
+### Building the CVO binary
+
+```console
+$ make build
+hack/build-go.sh
+Using version from git...
+Building github.com/openshift/cluster-version-operator (v1.0.0-942-g59e0826f-dirty)
+```
+
+### Building the CVO image
+
+The [`hack/build-image.sh`](../../hack/build-image.sh) script builds a local CVO image:
+
+```console
+$ ./hack/build-image.sh
+INFO: Using version from git...
+...
+[2/2] COMMIT cluster-version-operator:v1.0.0-942-g59e0826f-dirty
+--> 98ff149964f
+Successfully tagged localhost/cluster-version-operator:v1.0.0-942-g59e0826f-dirty
+```
+
+### Publishing a development CVO image
+
+The [`hack/push-image.sh`](../../hack/push-image.sh) script publishes
+a [locally-built CVO image](#building-the-cvo-image) to a remote repository:
+
+```console
+$ REPO=<your personal repo, such as quay.io/login> ./hack/push-image.sh
+```
+
+This pushes `${VERSION}` and `latest` tags to `${REPO}/origin-cluster-version-operator`, where `${VERSION}` encodes the
+Git commit used to build the image.
+
+### Building and publishing a release payload image with development CVO
+
+After publishing a [development CVO image](#publishing-a-development-cvo-image), you can build a release payload image
+that will contain all manifests from an existing release payload and the development CVO binary:
+
+```console
+$ oc adm release new --from-release=quay.io/openshift-release-dev/ocp-release:4.11.18-x86_64 \
+                     --to-image-base=${REPO}/origin-cluster-version-operator:latest \
+                     --image=${REPO}/ocp-release:latest
+```
+
+## Testing CVO
+
+### Unit tests
+
+Run `make test` to execute all unit tests.
+
+### Integration tests
+
+The [`hack/test-integration.sh`](../../hack/test-integration.sh) script executes integration tests against an OpenShift
+cluster. It requires `$KUBECONFIG` with administrator credentials. Only execute integration tests against disposable
+testing clusters.
+
+```console
+$ export KUBECONFIG=<admin kubeconfig path>
+$ ./hack/test-integration.sh
+```
+
+### Replace cluster's CVO with development CVO release payload image
+
+After publishing
+a [release payload image with development CVO](#building-and-publishing-a-release-payload-image-with-development-cvo),
+you can inject its pullspec into the `cluster-version-operator` Deployment in an existing cluster. Only do this against
+disposable testing clusters.
+
+```console
+$ pullspec=${REPO}/ocp-release:latest
+
+$ imagePatch='{"op":"replace","path":"/spec/template/spec/containers/0/image","value":"'"$pullspec"'"}'
+$ releaseImageArgPatch='{"op":"replace","path":"/spec/template/spec/containers/0/args/1","value":"--release-image='"$pullspec"'"}'
+$ oc patch -n openshift-cluster-version deployment cluster-version-operator --type json --patch="[$imagePatch,$releaseImageArgPatch]"
+deployment.apps/cluster-version-operator patched
+```
+
+### Advanced testing scenarios
+
+- [Feed custom upgrade graphs to CVO](feed-cvo-custom-graphs.md)
+- [Run local CVO against a remote cluster](run-cvo-locally.md)

hack/build-image.sh

@@ -22,4 +22,4 @@ if [ -z ${VERSION_OVERRIDE+a} ]; then
 fi
 
 set -x
-podman build -t "cluster-version-operator:${VERSION_OVERRIDE}" -f Dockerfile --no-cache
+podman build -t "cluster-version-operator:${VERSION_OVERRIDE}" -f Dockerfile --no-cache

hack/update-vendor.sh

@@ -10,5 +10,3 @@ cd "$(git rev-parse --show-cdup)"
 # Run dep.
 go mod vendor
 go mod verify
-
-(cd hack && ./update-codegen.sh)

hack/verify-style.sh

@@ -36,8 +36,5 @@ echo "Running yamllint..."
 YAMLS=$(find . -path ./vendor -prune -o -name '*.yaml' | grep -v vendor)
 yamllint -c hack/yamllint-config.yaml -s $YAMLS
 
-echo "Running verify code-generators"
-(cd hack && ./verify-codegen.sh)
-
 echo "Done!"
 exit ${rc}