doc/design/milestone-0.0.7/csv-generation.md: remove 'describe.yaml' …

…requirement; users are now expected to modify their CSV directly

doc/design/milestone-0.0.7/csv-generation.md

@@ -20,7 +20,7 @@ The `operator-sdk generate olm-catalog` command currently produces a generic CSV
 
 1. Create a new CSV, with the same location and naming convention as exists currently, using available data in yaml manifests and Golang source files.
 
-    1. `renderCSV` will check for an existing CSV in `deploy`. Upon not finding one, a [`ClusterServiceVersion` instance][olm-code-csv-struct], defined by the OLM, is created and fields easily derived from operator metadata, such as Kubernetes API `ObjectMeta`, are populated.
+    1. `renderCSV` will check for an existing CSV in `deploy`. Upon not finding one, a [`ClusterServiceVersion` instance][olm-csv-struct-code], defined by the OLM, is created and fields easily derived from operator metadata, such as Kubernetes API `ObjectMeta`, are populated.
     1. `renderCSV` will search `deploy` for manifests that contain yaml objects a CSV uses, such as a `Deployment` Kubernetes API resource, and cache found objects in a CSV struct
     1. Once this search completes, every cache instance field populated will be written back to the CSV yaml file. Note that individual yaml objects are overwritten and not the entire file.
 
@@ -42,7 +42,7 @@ type CSVUpdater interface {
 }
 ```
 
-`Apply` will use data from the `CSVUpdater` implementer to operate on `*v1alpha1.ClusterServiceVersion` instance fields relevant to that updater. The OLM defines the entire CSV spec [in Golang][olm-code-csv-spec] as a (versioned) hierarchy of `struct` components, each of which the SDK can alias to implement `CSVUpdater`.
+`Apply` will use data from the `CSVUpdater` implementer to operate on `*v1alpha1.ClusterServiceVersion` instance fields relevant to that updater. The OLM defines the entire CSV spec [in Golang][olm-csv-spec-code] as a (versioned) hierarchy of `struct` components, each of which the SDK can alias to implement `CSVUpdater`.
 
 Once sub-step 2 is reached when creating or updating a CSV, `renderCSV` will extract each yaml document discovered, and pass document data into a dispatcher function. The dispatcher selects the correct `CSVUpdater` to populate based on the documents' `Kind` yaml object, a manifest type identifier used in all (*TODO*: verify) operator manifests. The SDK accesses the latest version of CSV format and maintains OLM compatibility by leveraging the OLM spec implementations, rather than implementing the spec locally.
 
@@ -123,76 +123,40 @@ func (us *CSVInstallStrategyUpdate) Apply(csv *v1alpha1.ClusterServiceVersion) e
 
 ### User-defined yaml objects
 
-Many CSV component objects cannot be populated using generated, non-SDK-specific manifests. These objects are mostly human-written, English metadata about the operator and various CRD's. A file, `describe.yaml`, should be written by a user with which the SDK can populate CSV objects; this file should live in the `deploy` directory. `describe.yaml` will have the following format:
+Many CSV component objects cannot be populated using generated, non-SDK-specific manifests. These objects are mostly human-written, English metadata about the operator and various CRD's. Users must directly modify their CSV yaml file, adding personalized data to the following required objects. A lack of data in any of the required objects will generate an error on `operator-sdk build`.
 
-```yaml
-replaces: test-operator.0.1.0
-displayName: Test Operator
-description: |
+Required:
+- `displayName`: a public name to identify the operator.
+- `description`: a short description of the operator's functionality.
+- `keywords`: 1..N keywords describing the operator.
+- `maintainers`: 1..N human or organizational entities maintaining the operator, with a `name` and `email`.
+- `provider`: the operators' provider, with a `name`; usually an organization.
+- `labels`: 1..N `key`:`value` pairs to be used by operator internals.
+- `version`: semantic version of the operator, ex. `0.1.1`.
+- `customresourcedefinitions`: any CRD's the operator uses.
+	- **Note**: this field will be populated automatically by the SDKif any CRD yaml files are present in `deploy`; however, several objects require user input (more details in the [CSV CRD spec section][olm-csv-crd-doc]):
+		- `description`: description of the CRD.
+		- `resources`: any Kubernetes resources leveraged by the CRD, ex. `Pod`'s, `StatefulSet`'s.
+		- `specDescriptors`: UI hints for inputs and outputs of the operator.
 
-  The Test Operator for Kubernetes provides ...
+Optional:
+- `replaces`: the CSV being replaced by this CSV.
+- `links`: 1..N URL's to websites, documentation, etc. pertaining to the operator or application being managed, each with a `name` and `url`.
+- `selector`: selectors by which the operator can pair resources in a cluster.
+- `icon`: a base64-encoded icon unique to the operator, set in a `base64data` object with a `mediatype`. 
+- `maturity`: the operators' stage of development, ex. `beta`.
 
-keywords: ['test', 'application', ...]
+Further details on what data each field above should hold are found in the [CSV spec][olm-csv-spec-doc].
 
-maintainers:
-- name: Your Org
-  email: your@org.com
-...
-
-provider:
-  name: Your Org
-
-links:
-- name: Test
-  url: https://www.test.com/
-- name: Documentation
-  url: https://your.org/operators/test/docs/latest/
-  ...
-
-labels:
-  my-label-1: test.0.1.1
-  my-label-2: testoperator
-  ...
-
-selector:
-  matchLabels:
-    my-label-2: testoperator
-    ...
-
-icon:
-- base64data: PHN2ZyB3aWR0aD0iMjQ ... ==
-  mediatype: image/svg+xml
-
-maturity: beta
-version: 0.1.1
-
-customresourcedefinitions:
-  owned:
-  - name: test.coreos.com
-    description: A running Test instance
-    resources:
-    - kind: Pod
-      version: v1
-    ...
-    specDescriptors:
-    - description: Desired number of Pods for the cluster
-      displayName: Size
-      path: replicas
-      x-descriptors:
-      - 'urn:olm:descriptor:for:test:operator'
-      ...
-```
-
-Each of the above yaml objects corresponds to a homonymous `spec` object child described by the CSV [`spec` documentation][olm-csv-spec-doc]. [Here][describe-yaml-example] is a workable, complex example `describe.yaml` a Prometheus operator developer would write to assist the SDK in CSV generation.
-
-**Note**: Several yaml objects currently in `describe.yaml` can potentially be parsed from operator code; this SDK functionality will be addressed in a future design document.
+**Note**: Several yaml objects currently requiring user intervention can potentially be parsed from operator code; such SDK functionality will be addressed in a future design document.
 
 
 [olm-csv-definition]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/building-your-csv.md#what-is-a-cluster-service-version-csv
 [olm-description]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/README.md
 [catalog-description]:https://github.com/operator-framework/operator-lifecycle-manager/blob/master/Documentation/design/architecture.md#catalog-registry-design
-[olm-code-csv-struct]:https://github.com/operator-framework/operator-lifecycle-manager/blob/8799f39ef342dc1ff7430eba7a88c1c3c70cbdcc/pkg/api/apis/operators/v1alpha1/clusterserviceversion_types.go#L261
-[olm-code-csv-spec]:https://github.com/operator-framework/operator-lifecycle-manager/blob/8799f39ef342dc1ff7430eba7a88c1c3c70cbdcc/pkg/api/apis/operators/v1alpha1/clusterserviceversion_types.go
+[olm-csv-struct-code]:https://github.com/operator-framework/operator-lifecycle-manager/blob/8799f39ef342dc1ff7430eba7a88c1c3c70cbdcc/pkg/api/apis/operators/v1alpha1/clusterserviceversion_types.go#L261
+[olm-csv-spec-code]:https://github.com/operator-framework/operator-lifecycle-manager/blob/8799f39ef342dc1ff7430eba7a88c1c3c70cbdcc/pkg/api/apis/operators/v1alpha1/clusterserviceversion_types.go
 [olm-csv-spec-doc]:https://github.com/operator-framework/operator-lifecycle-manager/blob/16ff8f983b50503c4d8b8015bd0c14b5c7d6786a/Documentation/design/building-your-csv.md#building-a-cluster-service-version-csv-for-the-operator-framework
 [olm-csv-install-strat-doc]:https://github.com/operator-framework/operator-lifecycle-manager/blob/16ff8f983b50503c4d8b8015bd0c14b5c7d6786a/Documentation/design/building-your-csv.md#operator-install
-[describe-yaml-example]:example.describe.yaml
+[describe-yaml-example]:example.describe.yaml
+[olm-csv-crd-doc]:https://github.com/operator-framework/operator-lifecycle-manager/blob/16ff8f983b50503c4d8b8015bd0c14b5c7d6786a/Documentation/design/building-your-csv.md#owned-crds