From 8a196f4e36188f967dc2d2a37cd7849f03a12ccd Mon Sep 17 00:00:00 2001
From: david may <1301201+wass3r@users.noreply.github.com>
Date: Mon, 22 Apr 2024 09:54:29 -0500
Subject: [PATCH] enhance(stage): explain needs and name relationship (#400)

Co-authored-by: Easton Crupper <65553218+ecrupper@users.noreply.github.com>
Co-authored-by: David May <49894298+wass3rw3rk@users.noreply.github.com>
---
 content/tour/stages.md               | 4 ++++
 content/usage/stage_orchestration.md | 4 ++++
 2 files changed, 8 insertions(+)

diff --git a/content/tour/stages.md b/content/tour/stages.md
index c59ce178e..2aa6dc52a 100644
--- a/content/tour/stages.md
+++ b/content/tour/stages.md
@@ -60,6 +60,10 @@ stages:
           - echo "Goodbye, World"
 ```
 
+{{% alert title="Note:" color="info" %}}
+Be aware that `needs:` references stages by their name, which can be overridden by the `name` tag in the stage definition.
+{{% /alert %}}
+
 ```sh
 $ vela exec pipeline
 ...
diff --git a/content/usage/stage_orchestration.md b/content/usage/stage_orchestration.md
index 6be40e0a3..e308c088a 100644
--- a/content/usage/stage_orchestration.md
+++ b/content/usage/stage_orchestration.md
@@ -130,6 +130,10 @@ stages:
           - echo $VELA_REPO_FULL_NAME
 ```
 
+{{% alert title="Note:" color="info" %}}
+Be aware that `needs:` references stages by their name, which can be overridden by the `name` tag in the stage definition.
+{{% /alert %}}
+
 Consider a Vela build triggered by a `push` to `main`. We know that `run-first` will indeed run first, followed by `runtime-ruleset-stage` since it cannot be pruned due to its runtime rule. However, if we recall from our first example, when the _entirety_ of a stage's step collection is pruned at compile-time, the stage disappears completely:
 
 ```yaml