clarify `needs context contains outputs from all jobs that are defined as a dependency of the current job`

[jsoref]

Code of Conduct

• [X] I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/actions/learn-github-actions/contexts#needs-context

What part(s) of the article would you like to see updated?

The needs context contains outputs from all jobs that are defined as a dependency of the current job. For more information on defining job dependencies, see "Workflow syntax for GitHub Actions."

Additional information

As noted in https://github.com/commercialhaskell/stack/pull/5869/files#r973830586, it's unclear whether the prose here means "only outputs for jobs that are explicitly defined as dependent on this job will have their information available via needs" or "needs will have access to the status of any jobs defined in a cascading manner as blocking this job".

Assuming it means the former, the fix would be something like:

The needs context contains outputs from all jobs that are explicitly defined in the current job as a dependency of the current job using the needs property. Note that this doesn't include implicitly needed jobs. For more information on defining job dependencies, see "Workflow syntax for GitHub Actions."

This does appear to correspond to the output here: https://github.com/jsoref/cascading-needs/actions/runs/3079668494/jobs/4976170085

If it means the latter,

The needs context contains outputs from all jobs that defined in the current job or any jobs it transitively needs via the needs property. For more information on defining job dependencies, see "Workflow syntax for GitHub Actions."

[cmwilson21]

👋 @jsoref Thanks so much for opening an issue! I'll triage this for the team to take a look :eyes:

[lucascosti]

Thanks for this, @jsoref. It does look like it's only directly-depenendent jobs that are covered by needs.

You (or anyone can) can feel free to open a PR. I would suggest wording like:

The needs context contains outputs from all jobs that are defined as a direct dependency of the current job. Note that this doesn't include implicitly dependent jobs (for example, dependent jobs of a dependent job). For more information on defining job dependencies, see "Workflow syntax for GitHub Actions."

[nawed2611]

Can I work on this issue?