From 1858117869dd72e1367d7d4d8a1a32b0243cbea8 Mon Sep 17 00:00:00 2001 From: Jason Hall Date: Tue, 8 Sep 2020 21:32:49 -0400 Subject: [PATCH] Remove documentation advocating for test builders Instead, recommend that users not use them, and link to the bug with more information/discussion. --- internal/builder/README.md | 15 +--- internal/builder/v1alpha1/README.md | 120 +--------------------------- internal/builder/v1alpha1/doc.go | 3 + internal/builder/v1beta1/README.md | 120 +--------------------------- internal/builder/v1beta1/doc.go | 4 +- 5 files changed, 12 insertions(+), 250 deletions(-) diff --git a/internal/builder/README.md b/internal/builder/README.md index 9dadbf9eda7..e641b24f63f 100644 --- a/internal/builder/README.md +++ b/internal/builder/README.md @@ -1,14 +1,3 @@ -# Builder package for tests +# PLEASE AVOID USING THIS PACKAGE -This package 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 currently two versionned builder supported: -- [`v1alpha1`](./v1alpha1) -- [`v1beta1`](./v1beta1) +See https://github.com/tektoncd/pipeline/issues/3178 for more information diff --git a/internal/builder/v1alpha1/README.md b/internal/builder/v1alpha1/README.md index b7557573a1d..e641b24f63f 100644 --- a/internal/builder/v1alpha1/README.md +++ b/internal/builder/v1alpha1/README.md @@ -1,119 +1,3 @@ -# Builder package for tests +# PLEASE AVOID USING THIS PACKAGE -This package 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. - -```go - // Definition - type TaskRunOp func(*v1alpha1.TaskRun) - func TaskRun(name, namespace string, ops ...TaskRunOp) *v1alpha1.TaskRun { - // […] - } - func TaskRunOwnerReference(kind, name string) TaskRunOp { - return func(t *v1alpha1.TaskRun) { - // […] - } - } - // Usage - t := TaskRun("foo", "bar", func(t *v1alpha1.TaskRun){ - // 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. - -## Example - -Let's look at a non-exhaustive example. - -```go -package builder_test - -import ( - "fmt" - "testing" - - "github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1" - tb "github.com/tektoncd/pipeline/internal/builder/v1alpha1" - corev1 "k8s.io/api/core/v1" -) - -func MyTest(t *testing.T) { - // You can declare re-usable modifiers - myStep := tb.Step("my-step", "myimage") - // … and use them in a Task definition - myTask := tb.Task("my-task", "namespace", tb.TaskSpec( - tb.Step("simple-step", "myotherimage", tb.Command("/mycmd")), - myStep, - )) - // … and another one. - myOtherTask := tb.Task("my-other-task", "namespace", - tb.TaskSpec(myStep, - tb.TaskInputs(tb.InputsResource("workspace", v1alpha1.PipelineResourceTypeGit)), - ), - ) - myClusterTask := tb.ClusterTask("my-task", tb.ClusterTaskSpec( - tb.Step("simple-step", "myotherimage", tb.Command("/mycmd")), - )) - // A simple definition, with a Task reference - myTaskRun := tb.TaskRun("my-taskrun", "namespace", tb.TaskRunSpec( - tb.TaskRunTaskRef("my-task"), - )) - // … or a more complex one with inline TaskSpec - myTaskRunWithSpec := tb.TaskRun("my-taskrun-with-spec", "namespace", tb.TaskRunSpec( - tb.TaskRunInputs( - tb.TaskRunInputsParam("myarg", "foo"), - tb.TaskRunInputsResource("workspace", tb.TaskResourceBindingRef("git-resource")), - ), - tb.TaskRunTaskSpec( - tb.TaskInputs( - tb.InputsResource("workspace", v1alpha1.PipelineResourceTypeGit), - tb.InputsParam("myarg", tb.ParamDefault("mydefault")), - ), - tb.Step("mycontainer", "myimage", tb.Command("/mycmd"), - tb.Args("--my-arg=$(inputs.params.myarg)"), - ), - ), - )) - // Pipeline - pipeline := tb.Pipeline("tomatoes", "namespace", - tb.PipelineSpec(tb.PipelineTask("foo", "banana")), - ) - // … and PipelineRun - pipelineRun := tb.PipelineRun("pear", "namespace", - tb.PipelineRunSpec("tomatoes", tb.PipelineRunServiceAccount("inexistent")), - ) - // And do something with them - // […] - if _, err := c.PipelineClient.Create(pipeline); err != nil { - t.Fatalf("Failed to create Pipeline `%s`: %s", "tomatoes", err) - } - if _, err := c.PipelineRunClient.Create(pipelineRun); err != nil { - t.Fatalf("Failed to create PipelineRun `%s`: %s", "pear", err) - } - // […] -} -``` +See https://github.com/tektoncd/pipeline/issues/3178 for more information diff --git a/internal/builder/v1alpha1/doc.go b/internal/builder/v1alpha1/doc.go index 968521d635d..7caa73a9db9 100644 --- a/internal/builder/v1alpha1/doc.go +++ b/internal/builder/v1alpha1/doc.go @@ -59,5 +59,8 @@ 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 diff --git a/internal/builder/v1beta1/README.md b/internal/builder/v1beta1/README.md index 1bf2c5ed888..e641b24f63f 100644 --- a/internal/builder/v1beta1/README.md +++ b/internal/builder/v1beta1/README.md @@ -1,119 +1,3 @@ -# Builder package for tests +# PLEASE AVOID USING THIS PACKAGE -This package 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. - -```go - // Definition - type TaskRunOp func(*v1beta1.TaskRun) - func TaskRun(name, namespace string, ops ...TaskRunOp) *v1beta1.TaskRun { - // […] - } - func TaskRunOwnerReference(kind, name string) TaskRunOp { - return func(t *v1beta1.TaskRun) { - // […] - } - } - // Usage - t := TaskRun("foo", "bar", func(t *v1beta1.TaskRun){ - // 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. - -## Example - -Let's look at a non-exhaustive example. - -```go -package builder_test - -import ( - "fmt" - "testing" - - "github.com/tektoncd/pipeline/pkg/apis/pipeline/v1beta1" - tb "github.com/tektoncd/pipeline/internal/builder/v1beta1" - corev1 "k8s.io/api/core/v1" -) - -func MyTest(t *testing.T) { - // You can declare re-usable modifiers - myStep := tb.Step("my-step", "myimage") - // … and use them in a Task definition - myTask := tb.Task("my-task", "namespace", tb.TaskSpec( - tb.Step("simple-step", "myotherimage", tb.Command("/mycmd")), - myStep, - )) - // … and another one. - myOtherTask := tb.Task("my-other-task", "namespace", - tb.TaskSpec(myStep, - tb.TaskInputs(tb.InputsResource("workspace", v1beta1.PipelineResourceTypeGit)), - ), - ) - myClusterTask := tb.ClusterTask("my-task", tb.ClusterTaskSpec( - tb.Step("simple-step", "myotherimage", tb.Command("/mycmd")), - )) - // A simple definition, with a Task reference - myTaskRun := tb.TaskRun("my-taskrun", "namespace", tb.TaskRunSpec( - tb.TaskRunTaskRef("my-task"), - )) - // … or a more complex one with inline TaskSpec - myTaskRunWithSpec := tb.TaskRun("my-taskrun-with-spec", "namespace", tb.TaskRunSpec( - tb.TaskRunInputs( - tb.TaskRunInputsParam("myarg", "foo"), - tb.TaskRunInputsResource("workspace", tb.TaskResourceBindingRef("git-resource")), - ), - tb.TaskRunTaskSpec( - tb.TaskInputs( - tb.InputsResource("workspace", v1beta1.PipelineResourceTypeGit), - tb.InputsParam("myarg", tb.ParamDefault("mydefault")), - ), - tb.Step("mycontainer", "myimage", tb.Command("/mycmd"), - tb.Args("--my-arg=$(inputs.params.myarg)"), - ), - ), - )) - // Pipeline - pipeline := tb.Pipeline("tomatoes", "namespace", - tb.PipelineSpec(tb.PipelineTask("foo", "banana")), - ) - // … and PipelineRun - pipelineRun := tb.PipelineRun("pear", "namespace", - tb.PipelineRunSpec("tomatoes", tb.PipelineRunServiceAccount("inexistent")), - ) - // And do something with them - // […] - if _, err := c.PipelineClient.Create(pipeline); err != nil { - t.Fatalf("Failed to create Pipeline `%s`: %s", "tomatoes", err) - } - if _, err := c.PipelineRunClient.Create(pipelineRun); err != nil { - t.Fatalf("Failed to create PipelineRun `%s`: %s", "pear", err) - } - // […] -} -``` +See https://github.com/tektoncd/pipeline/issues/3178 for more information diff --git a/internal/builder/v1beta1/doc.go b/internal/builder/v1beta1/doc.go index 968521d635d..0ae99fd3925 100644 --- a/internal/builder/v1beta1/doc.go +++ b/internal/builder/v1beta1/doc.go @@ -1,4 +1,4 @@ -/* + Copyright 2019 The Tekton Authors Licensed under the Apache License, Version 2.0 (the "License"); @@ -59,5 +59,7 @@ 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