Clarification of behavior for "needs" and "name" tags in pipeline stage docs

[mitruly]

Background When reading the example provided in the pipeline stages needs documentation, it is not obvious that the stage name is used for the needs value rather than the stage key.

Explanation The following pipeline works, which is described in the documentation:

stages:
   foo:
      steps:
         - name: step-1
            image: golang
            ...
   bar:
      needs: foo
      steps:
         - name: step-2
            image: golang
            ...

However, the following will not have the stage dependency:

stages:
   foo:
      name: "Foo stage"
      steps:
         - name: step-1
            image: golang
            ...
   bar:
      needs: foo
      steps:
         - name: step-2
            image: golang
            ...

This will only work if the stages.bar.needs value is set to"Foo stage".

It would be nice if the stage key (e.g. foo) could be used, rather than the override name that's intended for UI formatting.

[susangreve]

@mitruly - Can you help us understand why you are trying to rename your stage?

[cognifloyd]

I just ran into this. By default I try to add a descriptive name: to everything (ansible playbooks, StackStorm workflows, GitHub actions, Vela pipelines). So, this was very surprising behavior for me.