From e03b4b18e1ccb95f023992380fe3de5435dfd524 Mon Sep 17 00:00:00 2001
From: Easton Crupper <65553218+ecrupper@users.noreply.github.com>
Date: Tue, 14 Nov 2023 10:22:08 -0500
Subject: [PATCH] chore(reference): add metadata auto_cancel documentation
 (#386)

---
 content/reference/yaml/metadata.md | 45 ++++++++++++++++++++++++++----
 1 file changed, 40 insertions(+), 5 deletions(-)

diff --git a/content/reference/yaml/metadata.md b/content/reference/yaml/metadata.md
index 5b779c4b1..be95f602f 100644
--- a/content/reference/yaml/metadata.md
+++ b/content/reference/yaml/metadata.md
@@ -19,11 +19,12 @@ metadata:
 
 ## Tags
 
-| Tag             | Required | Type | Description                                                        |
-|-----------------|----------|------|--------------------------------------------------------------------|
-| `template`      | Y        | bool | Enables compiling the pipeline as a template.                      |
-| `clone`         | N        | bool | Enables injecting the default clone process.                       |
-| `render_inline` | N        | bool | Enables rendering without explicitly calling within the pipeline.  |
+| Tag             | Required | Type        | Description                                                        |
+|-----------------|----------|-------------|--------------------------------------------------------------------|
+| `template`      | Y        | bool        | Enables compiling the pipeline as a template.                      |
+| `clone`         | N        | bool        | Enables injecting the default clone process.                       |
+| `render_inline` | N        | bool        | Enables rendering without explicitly calling within the pipeline.  |
+| `auto_cancel`   | N        | (see below) | Auto canceling settings for pipelines.                             | 
 
 ### Usage
 
@@ -72,4 +73,38 @@ metadata:
   # in the resulting pipeline without referencing it in stages
   # or steps. 
   render_inline: false
+```
+
+#### The `auto_cancel` tag
+
+| Tag              | Default  | Type  | Description                                                                                  |
+|------------------|----------|-------|----------------------------------------------------------------------------------------------|
+| `pending`        | True     | bool  | Pending builds will be auto canceled if qualifying build is triggered                        |
+| `running`        | False    | bool  | Currently running builds will be auto canceled if qualifying build is triggered              |
+| `default_branch` | False    | bool  | Pushes to the default branch will also be auto canceled if a qualifying build is triggered.  |
+
+A **qualifying build** is defined as either:
+  * a _push_ build with the same _branch_ as another running/pending _push_ build
+  * a _pull request_ build with the same _head ref_ as another running/pending _pull request_ build
+
+These builds most often happen when a user pushes a new commit to a branch and quickly push a new commit. Using the `auto_cancel` block can help free up build space and eliminate pointless builds.
+
+By default, auto canceling is disabled altogether. However, if `running` or `default_branch` are specified, `pending` has a default value of `true` unless specified otherwise.
+
+```yaml
+---
+# pending & running will auto cancel, but not pushes to the default branch.
+metadata:
+  auto_cancel:
+    running: true 
+```
+
+```yaml
+---
+# running builds will auto cancel even if they are targeting the default branch, but pending builds will not.
+metadata:
+  auto_cancel:
+    pending: false
+    default_branch: true
+    running: true
 ```
\ No newline at end of file