docs: Add advice for pre-release image tag (v prefix support)

[polarathene]

Resolves: #422

---

This caveat was not easily apparent and has tripped up users. This addition should help raise awareness in advance of triggering the mistake.

The original issue that I provided the information on lacked some context about the reporters workflow config and inputs at the time. They were stating that v prefix was not always stripped. Recently I revisited the issue and confirmed that as of the current release of docker/metadata-action the v prefix stripping behaviour of input values/refs works as documented and expected.

The inverse, of wanting the image tag to always produce tags with a v prefix for semver/pep440 tags is a bit more complicated though (arguably a bug from converting rather than discarding tag patterns using major, minor, patch expressions).

---

Advice summary

The linked caveat highlights that depending on the input value/ref expected, the following examples can produce mixed tags with v prefix present or missing:

• Example A:

  tags: |
    pattern=v{{ version }}
    pattern=v{{ major }}.{{ minor }}
    pattern=v{{ major }}

  Outputs:

  # With release input `v1.2.3`:
  v1.2.3
  v1.2
  v1
  
  # With pre-release input `v1.2.3-alpha`:
  # (All three patterns changed to `pattern={{ version }}`, `v` in defined pattern dropped)
  1.2.3-alpha
  

• Example B:

  tags: |
    pattern={{ raw }}
    pattern={{ major }}.{{ minor }}
    pattern={{ major }}

  Outputs:

  # With release input `v1.2.3`:
  # (`pattern={{ raw }}` doesn't strip `v`)
  v1.2.3
  1.2
  1
  
  # With pre-release input `v1.2.3-alpha`:
  # (additionally major/minor patterns changed to `pattern={{ version }}`, results in tag with/without prefix)
  v1.2.3-alpha
  1.2.3-alpha
  

In both cases, the correction is to use ,prefix=v:

• Example A:

  tags: |
    pattern={{ version }},prefix=v
    pattern={{ major }}.{{ minor }},prefix=v
    pattern={{ major }},prefix=v

• Example B:
  Effectively the same as above but with {{ raw }} (discouraged due to semantics of {{ raw }} vs {{ version }} based on input value/ref, where v prefix is expected here for the raw input):

  tags: |
    pattern={{ raw }}
    pattern={{ major }}.{{ minor }},prefix=v
    pattern={{ major }},prefix=v

• Output in both cases (assuming correct input for B):

  # With release input `v1.2.3`:
  v1.2.3
  v1.2
  v1
  
  # With pre-release input `v1.2.3-alpha`:
  v1.2.3-alpha