Design doc csv generation

[estroz]

This PR contains a first stab at a design doc describing SDK generation of ClusterServiceVersion's (CSV's) for operators. Mechanisms and conventions described in this draft are suggestions, not necessarily features.

Check out #673 for a WIP implementation.

[lilic]

Few questions

[robszumski]

This looks great!

[ecordell]

This looks great, can't wait to try it out 😄

Should we talk about additional management features here, or should they go in another proposal? One concern of mine is helping sdk users understand how to build sets of updates, not just a single CSV. This would be dealing with channels, packages, replaces, etc. But these are all "a layer up" from what this proposal addresses.

[estroz]

@ecordell yeah that stuff should go in another proposal. This one is mostly for how CSV's will be generated from input data.

[shawn-hurley]

I am having a pretty difficult time following the proposal, and because of this, I am worried that I might be missing gaps in regards to the ansible operator. Sorry for not getting it.

Two things I notice even without following:

1. you mention aliasing the types and then adding a Apply method on them but in the example, you seem to be embedding the type and not aliasing it.

2. I don't understand where the user-supplied values are coming from and from what I think I read you will error if these are not set.

3. We are doing this on a build, but it seems that we will only ever have a single csv in the deploy folder? did I miss understand?

4. Are we sure that the yaml files in deploy (which seem to be mostly for "here get your thing running") are the correct source of truth that we should rely on?

What I might be proposing here is a different directory with different rules that might be bootstrapped from deploy but allows us to keep the deploy scripts "here run x and now your working" while another directory can start to remove stuff to take advantage of OLM offerings. Maybe this is starting to think about the "next level" stuff that Evan mentions.

It might be nice to help me understand if you add an expected user workflow section? with the different use cases, we are solving and what you expect the commands to be and what the output of each would be?

[estroz]

Points from our discussion of @shawn-hurley's comment out-of-band:

1. Changing alias -> embed in docs
2. User-supplied values are those not discernible from codified data, ex. English descriptions. Instead of raising errors when certain values are not present, the SDK will raise warnings. I will add notes on how this will work.
3. A larger discussion will be had about how we want to store CSV files, since there are two streams of thought:
   1. Always have one csv.yaml (like an RPM spec)
   2. Version the file itself, ex. csv.x.y.z.yaml
4. We may want to include a configuration file or extra flags so users can specify what files/directories they want parsed to create a CSV. Configuration is particularly important for users that have different testing and production data.

I'm going to add more notes on CSV generation/usage workflow, as well as a flow diagram.

[hasbro17]

Overall SGTM. Just need to clarify the nit on how the generator knows the CSV version while generating it.

[lilic]

Few nits and questions, but overall sounds sane to me :)

[shawn-hurley]

LGTM

I would like to see the answer to which command this will be apart of.

I will say that this does appear to be adding much more complexity to the build command, which will get more complex once we get the manage dockerfiles stuff completed. I think we may want to keep that in mind.

[hasbro17]

LGTM

I think this is good enough for the proposal.
Once we start iterating on the actual implementation we'll see how we can revisit the TODO's for managing multiple CSV versions.