No documentation of resource validation requirements

[jdcasey]

What constitutes a valid control-plane resource? What about a valid data-plane resource? What are required in these resources before work can transition from build workflows into test workflows, into release workflows? We need to formalize this more so we can understand the minimal (and allowable?) data elements necessary to drive work forward. If this is package-specific (eg. container images vs. other OCI things) then let's call that out too.

[github-actions[bot]]

This issue is stale because it has been open 90 days with no activity. Remove the state/stale label or comment, or this will be closed in 30 days.

[ralphbean]

@jdcasey how do you envision structuring that in the docs?

We could ask each subsystem to document that in some clear format in their subsystem page, i.e. integration-service.

[jdcasey]

@ralphbean I'd like to know under what conditions the test stage would refuse to run (or fail to run, lacking inputs)...and the same for the release stage, and the build stage if it applies there. IMO this is like API documentation or interface documentation, it's just among the largest-scale interfaces in the system. These are transition points, and each stage will have assumptions about the availability of inputs in order to do their work. But they should not be assumptions, they should be documented (and validated, ideally).

If we ever see a new build pipeline that varies to a large degree from the others, but is still meant to plug into the same test and release pipelines, then it'll have to provide the same parameters to those successive pipelines. That will be important to know for the people implementing that new variant build pipeline. It may be that this stuff lives in the enterprise contract now, and work cannot propagate across a pipeline boundary without satisfying the requirements of the contract. If so, we should be looking at how we can render that contract as documentation. Otherwise, we need something to document (and validate) the requirements of that boundary.

[jdcasey]

It's hard to address the structure question right now, because the docs for that service are entirely container image oriented.

But that's the exact problem I'm trying to highlight with this documentation request...when you try to expand scope on the system to handle more than just container images, the information required to run a test pipeline is likely to be more than simply Component Name, Application Name, and Image and spec.containerImage. Build pipelines where that set of information isn't sane, or where it's not a complete description of the build, will need changes in the test pipeline. It may mean that test pipelines are coupled to build pipelines, or at least they're both coupled to the same underlying packaging technology.

[github-actions[bot]]

This issue is stale because it has been open 90 days with no activity. Remove the state/stale label or comment, or this will be closed in 30 days.