docs(README): clarify how tags: set version

[br3ndonland]

Description

Closes #561

The README says,

The first tag in the list (higher priority) will be used as the image version for generated OCI label and version output.

That doesn't seem to be correct.

Example run here.

Workflow file had type=sha listed first:

- name: Set up metadata
  id: meta
  uses: docker/metadata-action@c1e51972afc2121e065aed6d45c65596fe445f3f # v5.8.0
  with:
    images: ghcr.io/${{ github.repository }}
    flavor: |
      latest=${{ github.ref_type == 'tag' || github.ref_name == 'main' }}
    tags: |
      type=sha
      type=ref,event=branch

But then the action output was org.opencontainers.image.version=main.

Changes

This PR will update the wording in the README to clarify that version is determined by the highest-priority tag in the tags: input list, regardless of the order of the items in the input.

[polarathene]

The first tag in the list (higher priority)

If you read the priority attribute docs a little bit more you might see where your misunderstanding was?

metadata-action/README.md

Lines 794 to 810 in 318604b

	### `priority` attribute
	`priority=<int>` attribute is used to sort tags in the final list. The higher
	the value, the higher the priority. The first tag in the list (higher priority)
	will be used as the image version for generated OCI label and [`version` output](#outputs).
	Each tags `type` attribute has a default priority:
	| Attribute | Default priority |
	|------------|------------------|
	| `schedule` | `1000` |
	| `semver` | `900` |
	| `pep440` | `900` |
	| `match` | `800` |
	| `edge` | `700` |
	| `ref` | `600` |
	| `raw` | `200` |
	| `sha` | `100` |

Just like the first sentence clarifies, priority is used to sort the list of tags. Each tag type has a default priority value assigned, where ref (600) is higher than sha (100), that is why you observed the ref tag coming first.

When the docs refer to the first tag in the list to be selected, it is not referring to the unsorted tags input, but after sorted by priority. When you have multiple tags of the same priority how do you select which one to choose? The documented behaviour is the first one in that list is chosen (which implies tags preserves order of each tag of the equivalent priority).

    tags: |
      type=sha
      type=raw,value=hello
      type=raw,value=bello

The hello tag has a priority of 200, and it's declared before bello which is also 200 priority. The sha tag is lower priority, so hello is selected.

Your PR here would be removing this useful information.