veneer documentation (alpha)

[grokspawn]

This PR represents early reference documentation for the File-Based Catalogs (FBC) veneers functionality. The functionality is alpha and subject to breaking changes. These docs are intended to help us start the conversation with early adopters.

Signed-off-by: Jordan Keister jordan@nimblewidget.com

[grokspawn]

Thanks for all the review comments. I'm revising the doc now based on the input and hope to have it ready for a new review round shortly.

[joelanford]

Index Catalog Admins

This persona should not care about veneers. They should care only about the FBC generated from the veneer. Veneers are a tool for (and sometime by) operator authors only. If catalog maintainers implement things specific to veneers, it: a. Limits the ability of operator authors to make their own choices about how their package is organized b. Can make it difficult for catalog maintainers to make changes (e.g. if they want to stop supporting a veneer, they have to get every single individual package in that catalog to stop using it).

We should encourage catalog admins to define policies based on the content of the FBC, not veneers.

[joelanford]

Only other comments I have are related to the fact that these veneers are being introduced as alpha features.

With that in mind, IMO:

• We should keep veneer docs/examples as separate as possible from GA docs examples, and if the GA doc needs to refer to the veneers, it should be clear that the veneers are alpha. The main veneer docs should also very prominently let readers know that veneers are alpha.
• I don't think we know yet what all of the "why" answers are, and I don't think we should bias feedback we get by stating our presumed "why" answers. While these veneers are in alpha, I'd be inclined to say we should explicitly leave the "why" out, and state only the "what" and "how". And then perhaps have a call to action in the veneer doc to explicitly ask for feedback both positive and negative so that we can better answer the "why" when veneers graduate to GA.

[camilamacedo86]

HI @joelanford

Index Catalog Admins

This persona should not care about veneers. They should care only about the FBC generated from the veneer. Veneers are a tool for (and sometime by) operator authors only. If catalog maintainers implement things specific to veneers, it: a. Limits the ability of operator authors to make their own choices about how their package is organized b. Can make it difficult for catalog maintainers to make changes (e.g. if they want to stop supporting a veneer, they have to get every single individual package in that catalog to stop using it).

That makes sense totally sense. If we receive the veener schema we would have issues if/when we want to change something. +1

We should encourage catalog admins to define policies based on the content of the FBC, not veneers.

So, pipelines for example will ONLY receive the FBC content itself and not the veneers. This sorted out many of my questions/concerns by sure :-)

[grokspawn]

Sounds like we're all pulling in the same direction now, so I've done my best to implement the revisions I could glean from the tumultuous conversations.
I'm taking off the WIP label, and I would appreciate all the /lgtm-ers to take a look again so we can progress this.
And for /hold-ers to review and indicate if their concerns are assuaged.

[exdx]

/lgtm

[grokspawn]

removed the hold as we resolved the conversational thread which spawned it, but didn't clean up all the impacts.

[perdasilva]

/approve

[openshift-ci[bot]]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: grokspawn, perdasilva

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files: - ~~[OWNERS](https://github.com/operator-framework/olm-docs/blob/master/OWNERS)~~ [perdasilva] Approvers can indicate their approval by writing `/approve` in a comment Approvers can cancel approval by writing `/approve cancel` in a comment