Merge pull request #1111 from adambkaplan/deprecate-alpha-features

Deprecate alpha features

deploy/crds/shipwright.io_buildruns.yaml

@@ -72,8 +72,11 @@ spec:
                 description: BuildSpec refers to an embedded build specification
                 properties:
                   builder:
-                    description: Builder refers to the image containing the build
-                      tools inside which the source code would be built.
+                    description: "Builder refers to the image containing the build
+                      tools inside which the source code would be built. \n NOTICE:
+                      Builder is deprecated, and will be removed in a future release.
+                      Build strategies which rely on \"builder\" should provide an
+                      equivalent parameter instead."
                     properties:
                       annotations:
                         additionalProperties:
@@ -103,9 +106,11 @@ spec:
                     - image
                     type: object
                   dockerfile:
-                    description: Dockerfile is the path to the Dockerfile to be used
+                    description: "Dockerfile is the path to the Dockerfile to be used
                       for build strategies which bank on the Dockerfile for building
-                      an image.
+                      an image. \n NOTICE: Dockerfile is deprecated, and will be removed
+                      in a future release. Build strategies which rely on \"dockerfile\"
+                      should provide an equivalent parameter instead."
                     type: string
                   env:
                     description: Env contains additional environment variables that
@@ -419,8 +424,10 @@ spec:
                         type: string
                     type: object
                   sources:
-                    description: Sources slice of BuildSource, defining external build
-                      artifacts complementary to VCS (`.spec.source`) data.
+                    description: "Sources slice of BuildSource, defining external
+                      build artifacts complementary to VCS (`.spec.source`) data.
+                      \n NOTICE: Multiple sources in a build are deprecated. This
+                      feature will be removed in a future release."
                     items:
                       description: BuildSource remote artifact definition, also known
                         as "sources". Simple "name" and "url" pairs, initially without
@@ -2350,7 +2357,9 @@ spec:
                   be set if it is empty
                 properties:
                   generate:
-                    description: If generates a new ServiceAccount for the build
+                    description: "If generates a new ServiceAccount for the build
+                      \n NOTICE: Generated ServiceAccounts are deprecated, and will
+                      be removed in a future release."
                     type: boolean
                   name:
                     description: 'Name of the referent; More info: http://kubernetes.io/docs/user-guide/identifiers#names'
@@ -3877,8 +3886,11 @@ spec:
                 description: BuildSpec is the Build Spec of this BuildRun.
                 properties:
                   builder:
-                    description: Builder refers to the image containing the build
-                      tools inside which the source code would be built.
+                    description: "Builder refers to the image containing the build
+                      tools inside which the source code would be built. \n NOTICE:
+                      Builder is deprecated, and will be removed in a future release.
+                      Build strategies which rely on \"builder\" should provide an
+                      equivalent parameter instead."
                     properties:
                       annotations:
                         additionalProperties:
@@ -3908,9 +3920,11 @@ spec:
                     - image
                     type: object
                   dockerfile:
-                    description: Dockerfile is the path to the Dockerfile to be used
+                    description: "Dockerfile is the path to the Dockerfile to be used
                       for build strategies which bank on the Dockerfile for building
-                      an image.
+                      an image. \n NOTICE: Dockerfile is deprecated, and will be removed
+                      in a future release. Build strategies which rely on \"dockerfile\"
+                      should provide an equivalent parameter instead."
                     type: string
                   env:
                     description: Env contains additional environment variables that
@@ -4224,8 +4238,10 @@ spec:
                         type: string
                     type: object
                   sources:
-                    description: Sources slice of BuildSource, defining external build
-                      artifacts complementary to VCS (`.spec.source`) data.
+                    description: "Sources slice of BuildSource, defining external
+                      build artifacts complementary to VCS (`.spec.source`) data.
+                      \n NOTICE: Multiple sources in a build are deprecated. This
+                      feature will be removed in a future release."
                     items:
                       description: BuildSource remote artifact definition, also known
                         as "sources". Simple "name" and "url" pairs, initially without

deploy/crds/shipwright.io_builds.yaml

@@ -59,8 +59,11 @@ spec:
             description: BuildSpec defines the desired state of Build
             properties:
               builder:
-                description: Builder refers to the image containing the build tools
-                  inside which the source code would be built.
+                description: "Builder refers to the image containing the build tools
+                  inside which the source code would be built. \n NOTICE: Builder
+                  is deprecated, and will be removed in a future release. Build strategies
+                  which rely on \"builder\" should provide an equivalent parameter
+                  instead."
                 properties:
                   annotations:
                     additionalProperties:
@@ -90,8 +93,11 @@ spec:
                 - image
                 type: object
               dockerfile:
-                description: Dockerfile is the path to the Dockerfile to be used for
-                  build strategies which bank on the Dockerfile for building an image.
+                description: "Dockerfile is the path to the Dockerfile to be used
+                  for build strategies which bank on the Dockerfile for building an
+                  image. \n NOTICE: Dockerfile is deprecated, and will be removed
+                  in a future release. Build strategies which rely on \"dockerfile\"
+                  should provide an equivalent parameter instead."
                 type: string
               env:
                 description: Env contains additional environment variables that should
@@ -397,8 +403,10 @@ spec:
                     type: string
                 type: object
               sources:
-                description: Sources slice of BuildSource, defining external build
-                  artifacts complementary to VCS (`.spec.source`) data.
+                description: "Sources slice of BuildSource, defining external build
+                  artifacts complementary to VCS (`.spec.source`) data. \n NOTICE:
+                  Multiple sources in a build are deprecated. This feature will be
+                  removed in a future release."
                 items:
                   description: BuildSource remote artifact definition, also known
                     as "sources". Simple "name" and "url" pairs, initially without
@@ -2010,7 +2018,8 @@ spec:
             - strategy
             type: object
           status:
-            description: BuildStatus defines the observed state of Build
+            description: "BuildStatus defines the observed state of Build \n NOTICE:
+              This is deprecated and will be removed in a future release."
             properties:
               message:
                 description: The message of the registered Build, either an error

docs/build.md

@@ -25,7 +25,7 @@ SPDX-License-Identifier: Apache-2.0
 A `Build` resource allows the user to define:
 
 - source
-- sources
+- sources (**this is deprecated, and will be removed in a future release**)
 - strategy
 - params
 - builder
@@ -51,6 +51,8 @@ When the controller reconciles it:
 
 ## Build Validations
 
+**Note: reported validations in build status are deprecated, and will be removed in a future release.**
+
 To prevent users from triggering `BuildRuns` (_execution of a Build_) that will eventually fail because of wrong or missing dependencies or configuration settings, the Build controller will validate them in advance. If all validations are successful, users can expect a `Succeeded` `status.reason`. However, if any validations fail, users can rely on the `status.reason` and `status.message` fields to understand the root cause.
 
 | Status.Reason | Description |
@@ -79,14 +81,14 @@ The `Build` definition supports the following fields:
   - [`metadata`](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/#required-fields) - Metadata that identify the CRD instance, for example the name of the `Build`.
   - `spec.source` - Refers to the location of the source code, for example a Git repository or source bundle image.
   - `spec.strategy` - Refers to the `BuildStrategy` to be used, see the [examples](../samples/buildstrategy)
-  - `spec.builder.image` - Refers to the image containing the build tools to build the source code. (_Use this path for Dockerless strategies, this is just required for `source-to-image` buildStrategy_)
+  - `spec.builder.image` - Refers to the image containing the build tools to build the source code. (_Use this path for Dockerless strategies, this is just required for `source-to-image` buildStrategy_) **This field has been deprecated, and will be removed in a future release.**
   - `spec.output`- Refers to the location where the generated image would be pushed.
   - `spec.output.credentials.name`- Reference an existing secret to get access to the container registry.
 
 - Optional:
   - `spec.paramValues` - Refers to a name-value(s) list to specify values for `parameters` defined in the `BuildStrategy`.
-  - `spec.dockerfile` - Path to a Dockerfile to be used for building an image. (_Use this path for strategies that require a Dockerfile_)
-  - `spec.sources` - [Sources](#Sources) describes a slice of artifacts that will be imported into the project context before the actual build process starts.
+  - `spec.dockerfile` - Path to a Dockerfile to be used for building an image. (_Use this path for strategies that require a Dockerfile_). **This field has been deprecated, and will be removed in a future release.**
+  - `spec.sources` - [Sources](#Sources) describes a slice of artifacts that will be imported into the project context before the actual build process starts. **This field has been deprecated, and will be removed in a future release.**
   - `spec.timeout` - Defines a custom timeout. The value needs to be parsable by [ParseDuration](https://golang.org/pkg/time/#ParseDuration), for example, `5m`. The default is ten minutes. You can overwrite the value in the `BuildRun`.
   - `metadata.annotations[build.shipwright.io/build-run-deletion]` - Defines if delete all related BuildRuns when deleting the Build. The default is `false`.
   - `spec.output.annotations` - Refers to a list of `key/value` that could be used to [annotate](https://github.com/opencontainers/image-spec/blob/main/annotations.md) the output image.
@@ -415,6 +417,8 @@ Here, we pass three items in the `build-args` array:
 
 ### Defining the Builder or Dockerfile
 
+**Note: Builder and Dockerfile options are deprecated, and will be removed in a future release.**
+
 In the `Build` resource, you use the `spec.builder` or `spec.dockerfile` parameters to specify the image that contains the tools to build the final image. For example, the following Build definition specifies a `Dockerfile` image.
 
 ```yaml
@@ -708,6 +712,8 @@ spec:
 
 ### Sources
 
+**Note: This feature has been deprecated, and will be removed in a future release**.
+
 Sources represent remote artifacts, as in external entities added to the build context before the actual Build starts. Therefore, you may employ `.spec.sources` to download artifacts from external repositories.
 
 ```yaml

docs/buildrun.md

@@ -165,7 +165,7 @@ spec:
     name: pipeline
 ```
 
-You can also use set the `spec.serviceAccount.generate` path to `true`. This will generate the service account during runtime for you. The name of the generated service account is the name of the BuildRun.
+You can also use set the `spec.serviceAccount.generate` path to `true`. This will generate the service account during runtime for you. The name of the generated service account is the name of the BuildRun. **This field is deprecated, and will be removed in a future release.**
 
 _**Note**_: When the service account is not defined, the `BuildRun` uses the `pipeline` service account if it exists in the namespace, and falls back to the `default` service account.
 

pkg/apis/build/v1alpha1/build_source.go

@@ -17,6 +17,8 @@ const LocalCopy BuildSourceType = "LocalCopy"
 
 // HTTP defines a (HTTP) remote artifact, which will be downloaded into the build POD, right before
 // the build process starts. Represents a remote dependency.
+//
+// NOTICE: HTTP artifact downloads are deprecated. This feature will be removed in a future release.
 const HTTP BuildSourceType = "HTTP"
 
 // BuildSource remote artifact definition, also known as "sources". Simple "name" and "url" pairs,

pkg/apis/build/v1alpha1/build_types.go

@@ -118,6 +118,8 @@ type BuildSpec struct {
 	// (`.spec.source`) data.
 	//
 	// +optional
+	//
+	// NOTICE: Multiple sources in a build are deprecated. This feature will be removed in a future release.
 	Sources []BuildSource `json:"sources,omitempty"`
 
 	// Trigger defines the scenarios where a new build should be triggered.
@@ -132,13 +134,19 @@ type BuildSpec struct {
 	// Builder refers to the image containing the build tools inside which
 	// the source code would be built.
 	//
+	// NOTICE: Builder is deprecated, and will be removed in a future release.
+	// Build strategies which rely on "builder" should provide an equivalent parameter instead.
+	//
 	// +optional
 	Builder *Image `json:"builder,omitempty"`
 
 	// Dockerfile is the path to the Dockerfile to be used for
 	// build strategies which bank on the Dockerfile for building
 	// an image.
 	//
+	// NOTICE: Dockerfile is deprecated, and will be removed in a future release.
+	// Build strategies which rely on "dockerfile" should provide an equivalent parameter instead.
+	//
 	// +optional
 	Dockerfile *string `json:"dockerfile,omitempty"`
 
@@ -220,6 +228,8 @@ type Image struct {
 }
 
 // BuildStatus defines the observed state of Build
+//
+// NOTICE: This is deprecated and will be removed in a future release.
 type BuildStatus struct {
 	// The Register status of the Build
 	// +optional

pkg/apis/build/v1alpha1/buildrun_types.go

@@ -219,6 +219,8 @@ type ServiceAccount struct {
 	// +optional
 	Name *string `json:"name,omitempty"`
 	// If generates a new ServiceAccount for the build
+	//
+	// NOTICE: Generated ServiceAccounts are deprecated, and will be removed in a future release.
 	// +optional
 	Generate *bool `json:"generate,omitempty"`
 }