Automatic merge of gitlab-org/gitlab-ce master

doc/development/testing_guide/best_practices.md

 # Testing best practices
 
+## Test Design
+
+Testing at GitLab is a first class citizen, not an afterthought. It's important we consider the design of our tests 
+as we do the design of our features. 
+
+When implementing a feature, we think about developing the right capabilities the right way, which helps us 
+narrow our scope to a manageable level. When implementing tests for a feature, we must think about developing 
+the right tests, but then cover _all_ the important ways the test may fail, which can quickly widen our scope to 
+a level that is difficult to manage.
+
+Test heuristics can help solve this problem. They concisely address many of the common ways bugs 
+manifest themselves within our code. When designing our tests, take time to review known test heuristics to inform 
+our test design. We can find some helpful heuristics documented in the Handbook in the 
+[Test Design](https://about.gitlab.com/handbook/engineering/quality/guidelines/test-engineering/test-design/) section.
+
 ## Test speed
 
 GitLab has a massive test suite that, without [parallelization], can take hours

doc/development/testing_guide/index.md

@@ -33,7 +33,7 @@ changes should be tested.
 
 ## [Testing best practices](best_practices.md)
 
-Everything you should know about how to write good tests: RSpec, FactoryBot,
+Everything you should know about how to write good tests: Test Design, RSpec, FactoryBot,
 system tests, parameterized tests etc.
 
 ---

doc/topics/autodevops/index.md

@@ -1022,10 +1022,9 @@ planned for a subsequent release.
   buildpack](#custom-buildpacks).
 - Auto Test may fail because of a mismatch between testing frameworks. In this
   case, you may need to customize your `.gitlab-ci.yml` with your test commands.
-- Auto Deploy may fail if it is unable to create a Kubernetes namespace and
-  service account for your project. See the
-  [troubleshooting failed deployments](../../user/project/clusters/index.md#troubleshooting-failed-deployment-jobs)
-  section to debug why these resources were not created.
+- Auto Deploy will fail if GitLab can not create a Kubernetes namespace and
+  service account for your project. For help debugging this issue, see
+  [Troubleshooting failed deployment jobs](../../user/project/clusters/index.md#troubleshooting-failed-deployment-jobs).
 
 ### Disable the banner instance wide
 

doc/user/project/clusters/index.md

@@ -548,25 +548,23 @@ service account of the cluster integration.
 ### Troubleshooting failed deployment jobs
 
 GitLab will create a namespace and service account specifically for your
-deployment jobs. These resources are created just before the deployment
-job starts. Sometimes there may be errors that cause their creation to fail.
+deployment jobs, immediately before the jobs starts.
 
-In such instances, your job will fail with the message:
+However, sometimes GitLab can not create them. In such instances, your job will fail with the message:
 
-```The job failed to complete prerequisite tasks```
+```text
+The job failed to complete prerequisite tasks
+```
 
-You will need to check the [logs](../../../administration/logs.md) to debug
-why the namespace and service account creation failed.
+To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs.md#sidekiqlog).
 
-A common reason for failure is that the token you gave GitLab did not have
-[`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
-privileges as GitLab expects.
+Common reasons for failure include:
 
-Another common problem is caused by a missing `KUBECONFIG` or `KUBE_TOKEN`.
-To be passed to your job, it must have a matching
-[`environment:name`](../../../ci/environments.md#defining-environments). If
-your job has no `environment:name` set, it will not be passed the Kubernetes
-credentials.
+- The token you gave GitLab did not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles)
+  privileges required by GitLab.
+- Missing `KUBECONFIG` or `KUBE_TOKEN` variables. To be passed to your job, they must have a matching
+  [`environment:name`](../../../ci/environments.md#defining-environments). If your job has no
+  `environment:name` set, it will not be passed the Kubernetes credentials.
 
 ## Monitoring your Kubernetes cluster **[ULTIMATE]**