Document all locations that variable substitution is available

Expected Behavior

We should write down all the places that a variable can be substituted in our CRDs.

Actual Behavior

It's a bit hit-or-miss; we demonstrate some places to substitute in this section: https://github.com/tektoncd/pipeline/blob/master/docs/tasks.md#using-variable-substitution but it doesn't look like we document all of the possible locations that are supported.

Proposal

My suggestion would be to update docs/variables.md with a table of all locations in our CRDs where variables will be successfully interpolated into.

Here are a couple places in our code where we perform substitutions:

• task apply replacements
• pipeline apply replacements

So documenting the locations would just require reading the various funcs called from these spots and recording all the fields that get modified. Not entirely sure if these are the only places that we apply replacements from though.

[psschwei]

I'll look into this one this week.

/assign @psschwei

[bobcatfish]

Hey @psschwei It looks like we actually already have this https://github.com/tektoncd/pipeline/blob/master/docs/variables.md 😨

If there's anything missing tho plz add :D otherwise maybe we should close this issue? Sorry for the confusion 😨 😨 😨

Just to clarify - this issue is about documenting where the variables can be used. The existing variables.md contents only document what the available variables are.

[bobcatfish]

Thanks @sbwsg ! Looks like there is work to do here after all, sorry for the (increased) confusion @psschwei XD

[psschwei]

No worries, thanks for the clarification!

[pritidesai]

@psschwei feel free to create PR with subset of changes if it's easier for you. There are many places variable substitutions happen at Task level, Pipeline level, etc. As a newbie to source code, might be easier to propose small changes 🥰

[pritidesai]

@sbwsg do we consider task results substitutions as a variable substitution ? 🤔 I would think so, right?

value: $(tasks.mytask.results.sum)

Yeah I would definitely consider that a variable substitution as well.