Annotations priority docs

pages/agent/v3/cli_annotate.md

@@ -37,6 +37,27 @@ steps:
 
 <%= image "annotations-styles.png", alt: "Screenshot of available annotation styles" %>
 
+## Annotation ordering
+
+Annotations are ordered by priority (highest to lowest) and then by most recently created. Priority can be set with the `--priority` option when creating the annotation with `buildkite-agent annotate`. Priority ranges from `1` to `10`, with `10` being the highest priority and `1` being the lowest. If priority is not set, the default priority is `3`. If two annotations have the same priority, the one created most recently will be displayed first.
+
+This is an example pipeline that showcases how to use priority to order annotations:
+
+```yaml
+steps:
+  - label:  "\:console\: Annotation Test"
+    command: |
+      buildkite-agent annotate 'Example 1 (Priority 1)' --context 'first' --priority 1
+      buildkite-agent annotate 'Example 2 (Priority 10)' --style 'info' --context 'second' --priority 10
+      buildkite-agent annotate 'Example 3 (Priority 4)' --style 'warning' --context 'third' --priority 4
+      buildkite-agent annotate 'Example 4 (Priority 4)' --style 'error' --context 'fourth' --priority 4
+      buildkite-agent annotate 'Example 5 (Priority 3, Default)' --style 'success' --context 'fifth'
+```
+
+Which would produce the following ordering:
+
+<%= image "annotations-priority.png", alt: "Screenshot of annotations with different priorities" %>
+
 ## Supported Markdown syntax
 
 We use CommonMark with GitHub Flavored Markdown extensions to provide consistent, unambiguous Markdown syntax.

pages/apis/rest_api/annotations.md

@@ -34,6 +34,7 @@ curl -H "Authorization: Bearer $TOKEN" \
     "id": "de0d4ab5-6360-467a-a34b-e5ef5db5320d",
     "context": "default",
     "style": "info",
+    "priority" : 3,
     "body_html": "<h1>My Markdown Heading</h1>\n<img src=\"artifact://indy.png\" alt=\"Belongs in a museum\" height=250 />",
     "created_at": "2019-04-09T18:07:15.775Z",
     "updated_at": "2019-08-06T20:58:49.396Z"
@@ -42,6 +43,7 @@ curl -H "Authorization: Bearer $TOKEN" \
     "id": "5b3ceff6-78cb-4fe9-88ae-51be5f145977",
     "context": "coverage",
     "style": "info",
+    "priority" : 3,
     "body_html": "Read the <a href=\"artifact://coverage/index.html\">uploaded coverage report</a>",
     "created_at": "2019-04-09T18:07:16.320Z",
     "updated_at": "2019-04-09T18:07:16.320Z"
@@ -123,6 +125,13 @@ Optional [request body properties](/docs/api#request-body-properties):
       <p class="Docs__api-param-eg"><em>Example:</em> <code>"coverage"</code></p>
     </td>
   </tr>
+  <tr>
+    <th><code>priority</code></th>
+    <td>
+      An integer value by which to order the annotations on the build. This allows influencing the order of annotations. Ranges from 1 to 10, with 10 being the highest priority and 1 being the lowest. If priority is not set, the default priority is 3.
+      <p class="Docs__api-param-eg"><em>Example:</em> <code>"coverage"</code></p>
+    </td>
+  </tr>
   <tr>
     <th><code>append</code></th>
     <td>