Annotations priority docs

[matthewborden]

Recently we've introduced the ability to control the ordering of build annotations using priority, a customer provided ordering. Priority is an integer value from 1 to 10 with 10 being the highest and 1 being the lowest. Annotations are ordered by priority then by the most recently created at annotation first.

This updates the Agent CLI docs with the new buildkite-agent annotate --priority 10 flag, and also updates the REST API docs to include the field when creating and reading annotations for a build.

[buildkite-docs-bot]

Preview URL: https://2683--bk-docs-preview.netlify.app

[123sarahj123]

amazing work!

my comments are just nit picks/optional suggestions ^_^

it's great! just not ticking bc I am not a snazzy documentation person 🥰

[123sarahj123]

Suggested change

	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.
	An integer value used to order the annotations on the build, allowing for controlled prioritization. Priority levels ranges from 1 to 10, with 10 being the highest priority and 1 being the lowest. If not specified, annotations default to a priority of 3.

seeing if I can make the phrasing just a little more concise :)

[gilesgas]

Since the code block doesn't hold the entire width of each line, I'd move the --priority X options to the first position, similar to how the --style options are in the first position (in the section above)...

Suggested change

	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'
	buildkite-agent annotate 'Example 1 (Priority 1)' --priority 1 --context 'first'
	buildkite-agent annotate 'Example 2 (Priority 10)' --priority 10 --style 'info' --context 'second'
	buildkite-agent annotate 'Example 3 (Priority 4)' --priority 4 --style 'warning' --context 'third'
	buildkite-agent annotate 'Example 4 (Priority 4)' --priority 4 --style 'error' --context 'fourth'
	buildkite-agent annotate 'Example 5 (Priority 3, Default)' --style 'success' --context 'fifth'