State that step-level env variables override pipeline-level values

[mokagio]

This PR updates the note regarding the environment variables overriding behavior in the documentation to reflect the behavior experienced in production.

Details

This pipeline:

env:
  GLOBAL: global value we don't try to override
  GLOBAL_OVERRIDE: if you read this, then the global value takes precendence

steps:
  - label: "Test for env variables resolution"
    command: |
      echo "GLOBAL = $$GLOBAL"
      echo "GLOBAL_OVERRIDE = $$GLOBAL_OVERRIDE"
      echo "LOCAL = $$LOCAL"
    env:
      LOCAL: local value
      GLOBAL_OVERRIDE: if you read this, then the global value was overridden by the local one

Results in this output:

GLOBAL = global value we don't try to override
GLOBAL_OVERRIDE = if you read this, then the global value was overridden by the local one
LOCAL = local value

That is, the value for GLOBAL_OVERRIDE set in the step env node takes precedence over the value set in the env node in the pipeline root.

You can verify the behavior in action here.

Rationale

I opened a PR directly, rather than going through an issue first, because the behavior I see in production is what I would expect from a hierarchical configuration system and I'm guessing the docs are either out of date or wrong.

It's possible my expectation is incorrect, in which case this PR should be closed and a fix should be issued in the way the agent (?) resolves the variables hierarchy.

Next Steps

I've checked the "Allow edits by maintainers" option, so you can take this over and reword my phrasing if needed.

---

Thanks! I love Buildkite ❤️

[plaindocs]

Hey @mokagio I love the level of detail you've gone to on this PR. :star2:

I did a little digging and it turns out that it isn't quite as straightforward as this though, apparently the behavior changes depending on whether you're using a YAML pipeline or the older visual step editor.

I'll work on making that clear in the docs.