docs/contribution-guidelines: improve formatting, remove specifics of tests

website/content/en/docs/contribution-guidelines/_index.md

@@ -1,7 +1,6 @@
 ---
 title: How to Contribute
-linkTitle: Contribution Guidelines
+linkTitle: Contribution Guide
 weight: 9
 description: Contribute to Operator SDK
 ---
-

website/content/en/docs/contribution-guidelines/developer-guide.md

@@ -1,97 +1,67 @@
 ---
-title: Development Environment
-weight: 30
+title: Development
+linkTitle: Development
+weight: 1
 ---
 
-This document explains how to setup your dev environment.
+## Installation
+
+### Prerequisites
 
-## Prerequisites
 - [git][git-tool]
-- [go][go-tool] version v1.13+
+- [go][go-tool] v1.13+
 
-## Download Operator SDK
+### Download Operator SDK
 
-Go to the [Operator SDK repo][repo-sdk] and follow the [fork guide][fork-guide] to fork, clone, and setup the local operator-sdk repository.
+Go to the [operator-sdk repo][repo-sdk] and follow the [fork guide][fork-guide] to fork and set up a local repository.
 
-## Build the Operator SDK CLI
+### Build the Operator SDK CLI
 
 Build the Operator SDK CLI `operator-sdk` binary:
 
 ```sh
-$ make install
+make install
 ```
 
-Then, now you are able to test and use the operator-sdk build using the source code.
-
 ## Testing
 
-The SDK includes many tests that are run as part of CI.
-To build the binary and run all tests (assuming you have a correctly configured environment),
-you can simple run:
-
-```sh
-$ make test-ci
-```
-
-If you simply want to run the unit tests, you can run:
-
-```sh
-$ make test
-```
-
-For more information on running testing and correctly configuring your environment,
-refer to the [`Running the Tests Locally`][running-the-tests] document. To incorporate code changes in your development environment see the [`Testing changes Locally`][testing-changes-locally] document.
-
-To run the lint checks done in the CI locally, run:
-
-```sh
-$ make lint
-```
-
-**NOTE** Note that for it is required to install `golangci-lint` locally. For more info see its [doc](https://github.com/golangci/golangci-lint#install)
-
-## How the operator-sdk binaries are built
-
-In the release process, the script [.release.sh][release-sh] is executed and it will call the [makefile][makefile] target [make release](https://github.com/operator-framework/operator-sdk/blob/master/Makefile#L113). To know more about the release process, see the [doc][release-doc] also see [operator-sdk releases](https://github.com/operator-framework/operator-sdk/releases).
-
-**NOTE** The Deploy stage (configured in [.travis.yml ][travis]) builds also execute the same [makefile][makefile] targets. This stage is executed against the master branch when a Pull Request is merged.
-
-## How to test the build of operator-sdk binaries
-
-Follow these steps to execute the Travis `Deploy` stage against your branch to demonstrate that the merge build will complete as expected.
+See the [testing][dev-testing] and [documentation][dev-docs] guides for more information.
 
-- Enable the Travis in your fork repository. For more info see [`To get started with Travis CI using GitHub`](https://docs.travis-ci.com/user/tutorial/#to-get-started-with-travis-ci-using-github) 
-- Create image repos in quay (or another registry that supports multi-arch images) for ansible, helm, and scorecard proxy. For each image type, you need repos for the manifest list and one for each architecture (e.g. `ansible-operator`, `ansible-operator-amd64`, `ansible-operator-s390x`, etc.)
+## Releasing
 
-**NOTE** Be sure to make each repository public.
+See the [release guide][dev-release] for more information.
 
-- Set the following environment variables in the Travis settings for your fork:
+## Continuous Integration (CI)
 
-    - `ANSIBLE_IMAGE` docker image name (e.g. `quay.io/joelanford/ansible-operator`)
-    - `HELM_IMAGE` same as above, but for helm
-    - `SCORECARD_PROXY_IMAGE` same as above, but for scorecard proxy
-    - `DOCKER_USERNAME` credentials for your repo
-    - `DOCKER_PASSWORD` credentials for your repo
-    - `DOCKER_CLI_EXPERIMENTAL`  set to `enabled` 
-    - `COVERALLS_TOKEN`  token to integrate the project with `https://coveralls.io/`. So, enable your fork in `https://coveralls.io/` and generate a token to allow it. 
+The operator-sdk repo uses [Travis CI][travis] to test each pull request and build images for both master commits
+and releases. You can alter these processes by modifying this [`.travis.yml`][travis.yml] config file.
 
-- Make a commit with `[travis deploy]` in the commit message on the branch with the changes.
-- Check the travis build for your branch in your fork (not the PR build in the operator-sdk repo, since we don't allow PRs to build images in the `operator-framework` quay repo.)
+### Testing builds with new architectures
 
-**NOTE** Post a link in the Pull Request to the Travis build page showing successful `Deploy` and `Deploy multi-arch manifest lists` stages with your changes.
+Follow these steps to execute the Travis `Deploy` stage against your branch
+to demonstrate that the merge build will complete as expected.
 
-See the project [README][sdk-readme] for more details.
+- Enable Travis in your fork repository. See [this guide][travis-setup] for more information.
+- Create public image repos for each image built by `make image-build`; make sure the registry used supports
+multi-arch images, like quay.io.
+  - For each image type, you need one repo for the manifest list and one for each architecture being tested.
+- Set each image variable (that ends in `_IMAGE`, not `_BASE_IMAGE`) found in the Makefile
+as an environment variable in `.travis.yml`, ex. `export SCORECARD_TEST_IMAGE=<registry>/<username>/scorecard-test:latest`
+- Create a PR with your configuration changes to _your_ fork, with the first commit message containing
+`[travis deploy]`.
+  - This commit is only for testing on your fork's PR. This commit/message should not be present in an operator-sdk
+  repo PR.
+- Ensure the image builds for that PR pass.
+- Create a PR to the operator-sdk repo with a description containing a link to the Travis build page
+showing a successful deployment stage with your changes.
 
 [git-tool]:https://git-scm.com/downloads
 [go-tool]:https://golang.org/dl/
 [repo-sdk]:https://github.com/operator-framework/operator-sdk
 [fork-guide]:https://help.github.com/en/articles/fork-a-repo
-[docker-tool]:https://docs.docker.com/install/
-[kubectl-tool]:https://kubernetes.io/docs/tasks/tools/install-kubectl/
-[sdk-readme]: https://github.com/operator-framework/operator-sdk/blob/master/README.md
-[running-the-tests]: ../testing/running-the-tests
-[testing-changes-locally]: ../local-changes 
-[makefile]: https://github.com/operator-framework/operator-sdk/blob/master/Makefile
-[travis]: https://github.com/operator-framework/operator-sdk/blob/master/.travis.yml
-[release-sh]: https://github.com/operator-framework/operator-sdk/blob/master/release.sh
-[release-doc]: ../release
+[dev-testing]: /docs/contribution-guidelines/testing
+[dev-docs]: /docs/contribution-guidelines/documentation
+[dev-release]: /docs/contribution-guidelines/releasing
+[travis]: https://docs.travis-ci.com/
+[travis.yml]: https://github.com/operator-framework/operator-sdk/blob/master/.travis.yml
+[travis-setup]: https://docs.travis-ci.com/user/tutorial/#to-get-started-with-travis-ci-using-github

website/content/en/docs/contribution-guidelines/documentation.md

@@ -0,0 +1,44 @@
+---
+title: Documentation
+linkTitle: Documentation
+weight: 20
+---
+
+This document discusses how to visually inspect documentation changes as they would be applied
+to the live website. All changes to documentation should be inspected locally before being pushed
+to a PR.
+
+## Prerequisites
+
+The docs are built with [Hugo][hugo] which can be installed along with the
+required extensions by following the [docsy install guide][docsy-install].
+
+Note: Be sure to install hugo-extended.
+
+We use `git submodules` to install the docsy theme. From the
+`operator-sdk` directory, update the submodules to install the theme.
+
+```sh
+git submodule update --init --recursive
+```
+
+## Build and Serve
+
+You can build and serve your docs to `localhost:1313`. From the `website/`
+directory run:
+
+```sh
+hugo server
+```
+
+Any changes will be included in real time.
+
+
+## Check Links
+
+`make test-links` will use containers to build html and check the links.
+Please consider running this locally before creating a PR to save CI resources.
+
+
+[hugo]:https://gohugo.io/
+[docsy-install]:https://www.docsy.dev/docs/getting-started/#prerequisites-and-installation

website/content/en/docs/contribution-guidelines/release.md → website/content/en/docs/contribution-guidelines/releasing.md

@@ -1,5 +1,6 @@
 ---
 title: Release Guide
+linkTitle: Releasing
 weight: 30
 ---
 

website/content/en/docs/contribution-guidelines/reporting-issues.md

@@ -1,6 +1,7 @@
 ---
 title: Reporting Issues
-weight: 30
+linkTitle: Reporting Issues
+weight: 40
 ---
 
 If any part of the operator-sdk project has bugs or documentation mistakes, please let us know by [opening an issue][operator-sdk-issue]. We treat bugs and mistakes very seriously and believe no issue is too small. Before creating a bug report, please check that an issue reporting the same problem does not already exist.

website/content/en/docs/contribution-guidelines/testing.md

@@ -0,0 +1,47 @@
+---
+title: Testing
+linkTitle: Testing
+weight: 10
+---
+
+On all PRs, a suite of static and cluster tests is run against your changes in a CI environment.
+These tests can also be run locally, which is discussed [below](#local-test-environment).
+
+Static tests consist of [unit][unit-tests], formatting, and doc link tests.
+
+Cluster tests consist of several test types:
+- End-to-end (e2e): simulate the "happy path" usage of the `operator-sdk` binary and resulting operator project.
+- Integration: test components of the `operator-sdk` binary and features of scaffolded projects that are
+bound to external projects, such as [OLM][olm].
+- Subcommand: ensure individual subcommands function as intended with a variety of input options.
+
+## Local Test Environment
+
+If running tests locally, access to a Kubernetes cluster of server version v1.11.3 or higher is required.
+These tests require `KUBECONFIG` be set or kubeconfig file be present in a default location like `$HOME/.kube/config`.
+
+You will also need to set up an `envtest` environment for cluster tests. Follow [this doc][envtest-setup]
+for setup instructions.
+
+### Local clusters
+
+Two options for testing with a local cluster are [minikube][minikube] and [kind][kind].
+Ensure `KUBECONFIG` is set correctly for the chosen cluster type.
+
+## Running Tests
+
+On any PR, the entire test suite is run against your changes in a CI environment.
+Therefore it is advantageous to run all tests before pushing changes to the remote repo:
+
+```sh
+make test-sanity test-links test-unit test-subcommand test-integration test-e2e
+```
+
+All the tests are run through the [`Makefile`][makefile]. Run `make help` for a full list of available tests.
+
+[unit-tests]: https://onsi.github.io/gomega/
+[olm]: https://olm.operatorframework.io/
+[minikube]: https://kubernetes.io/docs/setup/learning-environment/minikube/
+[kind]: https://kind.sigs.k8s.io/
+[envtest-setup]: /docs/building-operators/golang/references/envtest-setup
+[makefile]: https://github.com/operator-framework/operator-sdk/blob/master/Makefile