Proposal: Use `inputs` for both specs and include to make relationship more intuitive
Pipeline Components terminology
We had a few recent chats in meetings and slack about the initial names of some of the keywords for the Components MVC:
spec:inputs
include:with
As I worked on the docs for them, I started to feel more strongly that it was not intuitive: Add initial docs for spec and with (!117204 - merged)
It seems we had two general groups of thought:
- Folks who were quite familiar with other CI/CD frameworks that use similar terminology felt it was useful to use terms that others might also recognize from previous experience.
- Folks who were newer to CI/CD, or at least to GitLab CI/Cd found it harder to understand and thought other names like
parameters
,attributes
,fields
, would make it easier to intuit the behavior without knowing other frameworks. It's similar to API terminology, for example, which is widespread.
I recognize this is late in the game, but it was only when working on the docs that the difficulties with the terminology became clear to me.
Kamil mentioned that using inputs
also would make it easier to someday add the concept of outputs
.
So based on these discussions, I think inputs
does seem like a useful term. So perhaps the simplest way to make this easier to understand would be to change include:with
to include:inputs
so that the terms are aligned. This is still an industry term, so there should be familiarity with it. Also, I think it'll be easier for newer people to intuit the relationship between the component and your own pipeline. "This component requires these inputs, so I'll add the inputs to the includes
block". So these would work together:
-
spec:inputs
: Used in the component header, to define the inputs a component needs. -
include:inputs
: Used in the pipeline, to set the input values for the included component.