Merge pull request #107 from shipwright-io/qu1queee/beta_api

Add post on beta API and migration guidelines

content/en/blog/posts/2023-11-07-beta-api.md

@@ -0,0 +1,148 @@
+---
+title: "Introducing Shipwright Beta API"
+date: 2023-11-07T16:00:00-04:00
+draft: false
+author: "Enrique Encalada ([@qu1queee](https://github.com/qu1queee))"
+---
+
+About a year ago, we published a blog [post](https://shipwright.io/blog/2022/10/25/bringing-shipwright-to-beta-and-beyond/)
+in which we outline our vision and our values. Part of this vision was to advance
+our API to enhance its simplicity and consistency, and to signal a higher level of maturity.
+
+Today, as part of our release _v0.12.0_, we are introducing our _beta_ API. 
+The _beta_ API brings multiple changes as a result of accumulated experience operating
+the _alpha_ API and incorporating valuable user feedback.
+
+With the introduction of the _beta_ API, users can have confidence that our
+core components have been battle-tested, and using our different features is
+considered a safe practice.
+
+_We want to thank our community for their contributions and support in redefining this new API!_
+
+## Beta API
+
+The _beta_ API is available starting from the _v0.12.0_ release. The release is available 
+across our [cli](https://github.com/shipwright-io/cli), [operator](https://github.com/shipwright-io/operator) and [build](https://github.com/shipwright-io/build) repository.
+
+Within the _v0.12.0_ release, a conversion webhook has been introduced to ensure backward
+compatibility between the _v1alpha1_ and _v1beta1_. 
+
+We strongly encourage both current and future users to adopt the _beta_ API to benefit from
+its enhanced definition.
+
+
+## Migration guidelines
+
+### Deprecated fields
+
+| Resource |  Field                           | Alternative                             |
+|----------|----------------------------------|:---------------------------------------:|
+| Build    | `.spec.sources`                  | `.spec.source`                          |
+| Build    | `.spec.dockerfile`               | `spec.paramValues[]` with `dockerfile`  |
+| Build    | `.spec.builder`                  | none                                    |
+| Build    | `.spec.volumes[].description`    | none                                    |
+| BuildRun | `.spec.serviceAccount.generate`  | `.spec.serviceAccount` with `.generate` |
+| BuildRun | `.spec.sources`                  | `.spec.source`                          |
+| BuildRun | `.spec.volumes[].description`    | none                                    |
+
+
+### Changes to Build API fields
+
+|  Old field                       |                            New field                                     |
+|----------------------------------|:------------------------------------------------------------------------:|
+| `.spec.source.url`               |  `.spec.source.git.url`                                                  |
+| `.spec.source.bundleContainer`   |  `.spec.source.ociArtifact`                                              |
+| `.spec.sources` for `LocalCopy`  |  `.spec.source.local`                                                    |
+| `.spec.source.credentials`       |  `.spec.source.git.cloneSecret` or `.spec.source.ociArtifact.pullSecret` |
+| `.spec.output.credentials`       |  `.spec.output.pushSecret`                                               |
+
+
+See this example of the Git source type:
+
+```yaml
+# v1alpha1
+---
+apiVersion: shipwright.io/v1alpha1
+kind: Build
+metadata:
+  name: a-build
+spec:
+  source:
+    url: https://github.com/shipwright-io/sample-go
+    contextDir: docker-build
+  strategy:
+    name: buildkit
+    kind: ClusterBuildStrategy
+  output:
+    image: an-image
+
+# v1beta1
+---
+apiVersion: shipwright.io/v1beta1
+kind: Build
+metadata:
+  name: a-build
+spec:
+  source:
+    type: Git
+    git: 
+      url: https://github.com/shipwright-io/sample-go
+    contextDir: docker-build
+  strategy:
+    name: buildkit
+    kind: ClusterBuildStrategy
+  output:
+    image: an-image
+```
+
+
+### Changes to BuildRun API fields
+
+|  Old field                  |                 New field              |
+|-----------------------------|:--------------------------------------:|
+| `.spec.buildSpec`           | `.spec.build.spec`                     |
+| `.spec.buildRef`            | `.spec.build.name`                     |
+| `.spec.sources`             | `.spec.source` only for `Local`        |
+| `.spec.serviceAccount.generate` | `.spec.serviceAccount` with `.generate`|
+
+_Note: generated service accounts is a deprecated feature, and may be removed in a future release._
+
+See example:
+
+```yaml
+# v1alpha1
+---
+apiVersion: shipwright.io/v1alpha1
+kind: BuildRun
+metadata:
+  name: a-buildrun
+spec:
+  buildRef:
+    name: a-build
+  serviceAccount:
+    generate: true
+
+
+# v1beta1
+---
+apiVersion: shipwright.io/v1beta1
+kind: BuildRun
+metadata:
+  name: a-buildrun
+spec:
+  build:
+    name: a-build
+  serviceAccount: ".generate"
+```
+
+
+
+### Changes to Strategies API fields
+
+|  Old field   | New field |
+|--------------------|:-------------:|
+| `.spec.buildSteps` | `.spec.steps` |
+
+## References
+
+For more information, see [SHIP 0035](https://github.com/shipwright-io/community/blob/main/ships/0035-beta-api-changes.md).