Remove documentation advocating for test builders

Instead, recommend that users not use them, and link to the bug with
more information/discussion.

Also mark packages as Deprecated in godoc comments, which some IDEs
propagate and show as warnings to users.

internal/builder/README.md

@@ -1,14 +1,63 @@
-# Builder package for tests
+# PLEASE AVOID USING THESE PACKAGES
 
-This package holds `Builder` functions that can be used to create struct in
-tests with less noise.
+See https://github.com/tektoncd/pipeline/issues/3178 for more information
 
-One of the most important characteristic of a unit test (and any type of test
-really) is **readability**. This means it should be easy to read but most
-importantly it should clearly show the intent of the test. The setup (and
-cleanup) of the tests should be as small as possible to avoid the noise. Those
-builders exists to help with that.
+Instead of using these packages to define a Pipeline:
 
-There is currently two versionned builder supported:
-- [`v1alpha1`](./v1alpha1)
-- [`v1beta1`](./v1beta1)
+```go
+import tb "github.com/tektoncd/pipeline/internal/builder/v1beta1"
+
+p := tb.Pipeline("my-pipeline", tb.PipelineNamespace("my-namespace"), tb.PipelineSpec(
+	tb.PipelineDescription("Example Pipeline"),
+	tb.PipelineParamSpec("first-param", v1beta1.ParamTypeString, tb.ParamSpecDefault("default-value"), tb.ParamSpecDescription("default description")),
+	tb.PipelineTask("my-task", "task-name",
+		tb.PipelineTaskParam("stringparam", "value"),
+	),
+))
+```
+
+Just use the Go structs directly:
+
+```go
+import (
+	corev1 "k8s.io/api/core/v1"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1"
+)
+
+p := &v1beta1.Pipeline{
+	ObjectMeta: metav1.ObjectMeta{
+		Name:      "my-pipeline",
+		Namespace: "my-namespace",
+	},
+	Spec: v1beta1.PipelineSpec{
+		Description: "Test Pipeline",
+		Params: []v1beta1.ParamSpec{{
+			Name:        "first-param",
+			Type:        v1beta1.ParamTypeString,
+			Default: v1beta1.ArrayOrString{
+				Type:        v1beta1.ParamTypeString,
+				StringValue: "default-value",
+			},
+			Description: "default description",
+		}},
+		Tasks: []v1beta1.PipelineTask{{
+			Name:    "my-task",
+			TaskRef: &v1beta1.TaskRef{
+				Name:   "task-name",
+				Params: []v1beta1.Param{{
+					Name: "stringparam",
+					Value: v1beta1.ArrayOrString{
+						Type:        v1beta1.ParamTypeString,
+						StringValue: "value",
+					},
+				}},
+			},
+		}},
+	},
+}
+```
+
+It's more typing, but it's more consistent with other Go code, all fields are
+clearly named, and nobody has to write and test and maintain the wrapper
+functions.

internal/builder/v1alpha1/doc.go

@@ -18,46 +18,10 @@ limitations under the License.
 Package builder holds Builder functions that can be used to create
 struct in tests with less noise.
 
-One of the most important characteristic of a unit test (and any type
-of test really) is readability. This means it should be easy to read
-but most importantly it should clearly show the intent of the
-test. The setup (and cleanup) of the tests should be as small as
-possible to avoid the noise. Those builders exists to help with that.
-
-There is two types of functions defined in that package :
-
-	* Builders: create and return a struct
-	* Modifiers: return a function
-	  that will operate on a given struct. They can be applied to other
-	  Modifiers or Builders.
-
-Most of the Builder (and Modifier) that accepts Modifiers defines a
-type (`TypeOp`) that can be satisfied by existing function in this
-package, from other package *or* inline. An example would be the
-following.
-
-	// Definition
-	type TaskOp func(*v1alpha1.Task)
-	func Task(name string, ops ...TaskOp) *v1alpha1.Task {
-		// […]
-	}
-	func TaskNamespace(namespace string) TaskOp {
-		return func(t *v1alpha1.Task) {
-			// […]
-		}
-	}
-	// Usage
-	t := Task("foo", TaskNamespace("bar"), func(t *v1alpha1.Task){
-		// Do something with the Task struct
-		// […]
-	})
-
-The main reason to define the `Op` type, and using it in the methods
-signatures is to group Modifier function together. It makes it easier
-to see what is a Modifier (or Builder) and on what it operates.
-
 By convention, this package is import with the "tb" as alias. The
 examples make that assumption.
 
+Deprecated: This package is deprecated. See
+https://github.com/tektoncd/pipeline/issues/3178 for more information.
 */
 package builder