Provide more guidance on not using PipelineResources 🚧

This commit makes some updates to the migration guide:
- The section on how the inputs/outputs PipelineResources spec
  has changed is now at the end of the guide, since it's a bit confusing
  to tell ppl to try to migrate away from them and have the new syntax
  for these front and center at the same time
- There is now an example of how you can make a Pipeline that does the
  equivalent of what you used to get with a Task that used image and git
  resources

docs/migrating-v1alpha1-to-v1beta1.md

@@ -2,13 +2,13 @@
 
 - [Migrating From v1alpha1 to v1beta1](#migrating-from-v1alpha1-to-v1beta1)
   - [Inputs and Outputs](#inputs-and-outputs)
-    - [Input Params](#input-params)
+  - [PipelineResources are remaining alpha](#pipelineresources-and-catalog-tasks)
+    - [PipelineResource equivalent catalog tasks](#pipelineresource-equivalent-catalog-tasks)
+      - [Git Resource](#git-resource)
+      - [Pull Request Resource](#pull-request-resource)
+      - [Image Resource](#image-resource)
+      - [GCS Resource](#gcs-resource)
     - [Input and Output PipelineResources](#input-and-output-pipelineresources)
-  - [PipelineResources and Catalog Tasks](#pipelineresources-and-catalog-tasks)
-    - [Git Resource](#git-resource)
-    - [Pull Request Resource](#pull-request-resource)
-    - [Image Resource](#image-resource)
-    - [GCS Resource](#gcs-resource)
 
 This doc describes the changes you'll need to make when converting your `Task`s,
 `Pipeline`s, `TaskRun`s, and `PipelineRun`s from the `v1alpha1` `apiVersion` to
@@ -18,9 +18,8 @@ This doc describes the changes you'll need to make when converting your `Task`s,
 
 The `spec.inputs` and `spec.outputs` fields in `Tasks` are removed in `v1beta1`.
 `spec.inputs.params` is moved to `spec.params`. `spec.inputs.resources` becomes
-`spec.resources.inputs` and `spec.outputs.resources` becomes `spec.resources.outputs`.
-
-#### Input Params
+`spec.resources.inputs` and `spec.outputs.resources` becomes `spec.resources.outputs`,
+but [`PipelineResources` are remaining alpha](#pipelineresources-are-remaining-alpha).
 
 Params move from `spec.inputs.params` in v1alpha1 to just `spec.params` in v1beta1.
 
@@ -60,11 +59,152 @@ spec:
     value: https://example.com/foo.json
 ```
 
-#### Input and Output PipelineResources
+## PipelineResources and Catalog Tasks
+
+`PipelineResources` are remaining in alpha while the other resource kinds are
+promoted to beta. This is part of a deliberate effort to migrate users away
+from `PipelineResources` onto a broader suite of reusable `Tasks` provided by
+the Tekton catalog.
+
+_More on the reasoning and what's left to do in
+[Why aren't PipelineResources in Beta?](docs/resources.md#why-arent-pipelineresources-in-beta)._
+
+In the near-term `PipelineResources` will continue to be supported by Tekton.
+At some point the feature may well be deprecated and subsequently replaced.
+
+To ease migration away from `PipelineResources`
+[some types have an equivalent `Task` in the Catalog](#pipelineresource-equivalent-catalog-tasks).
+To use these replacement `Tasks` you will need to combine them with your existing `Tasks` via a `Pipeline`.
+
+For example, if you were using this `Task` which was fetching from `git` and building with
+`Kaniko`:
+
+```yaml
+apiVersion: tekton.dev/v1alpha1
+kind: Task
+metadata:
+  name: build-push-kaniko
+spec:
+  inputs:
+    resources:
+    - name: workspace
+      type: git
+    params:
+    - name: pathToDockerFile
+      description: The path to the dockerfile to build
+      default: /workspace/workspace/Dockerfile
+    - name: pathToContext
+      description: The build context used by Kaniko
+      default: /workspace/workspace
+  outputs:
+    resources:
+    - name: builtImage
+      type: image
+  steps:
+  - name: build-and-push
+    image: gcr.io/kaniko-project/executor:v0.17.1
+    env:
+    - name: "DOCKER_CONFIG"
+      value: "/tekton/home/.docker/"
+    args:
+    - --dockerfile=$(inputs.params.pathToDockerFile)
+    - --destination=$(outputs.resources.builtImage.url)
+    - --context=$(inputs.params.pathToContext)
+    - --oci-layout-path=$(inputs.resources.builtImage.path)
+    securityContext:
+      runAsUser: 0
+```
+
+_Note that using `PipelineResources` with this `Task` has an immediate downside in that it is
+coupled to `git`; one can't use the same `Task` with files that were obtained some other way._
+
+To do the same thing with the `git` catalog `Task` and the kaniko `Task` you will need to combine them in a
+`Pipeline`.
+
+For exmaple this Pipeline uses the Kaniko and `git` catalog Tasks:
+
+```yaml
+apiVersion: tekton.dev/v1beta1
+kind: Pipeline
+metadata:
+  name: kaniko-pipeline
+spec:
+  params:
+  - name: git-url
+  - name: git-revision
+  - name: image-name
+  - name: path-to-image-context
+  - name: path-to-dockerfile
+  workspaces:
+  - name: git-source
+  tasks:
+  - name: fetch-from-git
+    taskRef:
+      name: git-clone
+    params:
+    - name: url
+      value: $(params.git-url)
+    - name: revision
+      value: $(params.git-revision)
+    workspaces:
+    - name: output
+      workspace: git-source
+  - name: build-image
+    taskRef:
+      name: kaniko
+    params:
+    - name: IMAGE
+      value: $(params.image-name)
+    - name: CONTEXT
+      value: $(params.path-to-image-context)
+    - name: DOCKERFILE
+      value: $(params.path-to-docker-file)
+    workspaces:
+    - name: source
+      workspace: git-source
+  # If you want you can add a Task that uses the IMAGE_DIGEST from the kaniko task
+  # via $(tasks.build-image.results.IMAGE_DIGEST) - this was a feature we hadn't been
+  # able to fully delivery with the Image PipelineResource!
+```
+
+_Note that [the `image` `PipelineResource` is gone in this example](#image-resource) (replaced with
+a [`result`](docs/tasks.md#resultes)), and also that now the `Task` doesn't need to know anything
+about where the files come from that it builds from._
+
+### PipelineResource equivalent catalog Tasks
+
+#### Git Resource
+
+The [`git-clone` Task in the Catalog](https://github.com/tektoncd/catalog/tree/v1beta1/git)
+provides an equivalent to the Git Resource.
+
+#### Pull Request Resource
+
+The [`pullrequest` Task in the Catalog](https://github.com/tektoncd/catalog/tree/v1beta1/pullrequest)
+provides an equivalent to the PullRequest Resource.
+
+#### Image Resource
+
+The Image PipelineResource does not come with specific behaviour, it's simply a way to share
+a built image's digest with subsequent `Tasks` in a `Pipeline`. The same effect can be achieved
+using [`Task` results](./tasks.md#results) and [`Task` params](./tasks.md#parameters)
+
+For an example of how the Image PipelineResource can be replaced, see
+the [Kaniko Catalog Task](https://github.com/tektoncd/catalog/blob/v1beta1/kaniko/)
+which demonstrates writing the image digest to a result, and the
+[Buildah Catalog Task](https://github.com/tektoncd/catalog/blob/v1beta1/buildah/)
+which shows how to accept an image digest as a parameter.
+
+#### GCS Resource
+
+The [`gcs` Tasks in the Catalog](https://github.com/tektoncd/catalog/tree/v1beta1/gcs) provide
+an equivalent to the GCS Resource.
+
+### Input and Output PipelineResources
 
 In v1alpha1, `PipelineResources` were stored under `spec.inputs.resources` and
-`spec.outputs.resources`. In v1beta1 these change to `spec.resources.inputs` and
-`spec.resources.outputs`.
+`spec.outputs.resources`. If you are using `PipelineResources` with v1beta1 these
+change to `spec.resources.inputs` and `spec.resources.outputs`.
 
 Example v1alpha1 PipelineResources:
 
@@ -134,44 +274,4 @@ spec:
         params:
         - name: url
           value: gcr.io/foo/bar
-```
-
-## PipelineResources and Catalog Tasks
-
-PipelineResources are remaining in alpha while the other resource kinds are
-promoted to beta. This is part of a deliberate effort to migrate users away
-from PipelineResources onto a broader suite of reusable Tasks provided by
-the Tekton catalog.
-
-In the near-term `PipelineResources` will continue to be supported by Tekton.
-At some point the feature may well be deprecated and subsequently replaced.
-
-To ease migration away from PipelineResources some types have an equivalent
-Task in the Catalog.
-
-### Git Resource
-
-The [`git-clone` Task in the Catalog](https://github.com/tektoncd/catalog/tree/v1beta1/git)
-provides an equivalent to the Git Resource.
-
-### Pull Request Resource
-
-The [`pullrequest` Task in the Catalog](https://github.com/tektoncd/catalog/tree/v1beta1/pullrequest)
-provides an equivalent to the PullRequest Resource.
-
-### Image Resource
-
-The Image PipelineResource does not come with specific behaviour, it's simply a way to share
-a built image's digest with subsequent `Tasks` in a `Pipeline`. The same effect can be achieved
-using [`Task` results](./tasks.md#results) and [`Task` params](./tasks.md#parameters)
-
-For an example of how the Image PipelineResource can be replaced, see
-the [Kaniko Catalog Task](https://github.com/tektoncd/catalog/blob/v1beta1/kaniko/)
-which demonstrates writing the image digest to a result, and the
-[Buildah Catalog Task](https://github.com/tektoncd/catalog/blob/v1beta1/buildah/)
-which shows how to accept an image digest as a parameter.
-
-### GCS Resource
-
-The [`gcs` Tasks in the Catalog](https://github.com/tektoncd/catalog/tree/v1beta1/gcs) provide
-an equivalent to the GCS Resource.
+```

docs/resources.md

@@ -1107,7 +1107,7 @@ They also present challenges from a documentation perspective:
 - Perhaps the one thing you can say about the `PipelineResource` CRD is that it can create
   side-effects for your `Tasks`.
 
-### Next steps
+### What's still missing
 
 So what are PipelineResources still good for?  We think we've identified some of the most important things: