Better document `latest` tag (`flavor.latest=auto` default vs `type=raw,value=latest`)

[polarathene]

Description

This issue is primarily to better reference comments of mine on the topic from different issues. I've revised each of those and quoted them inline below for convenience.

The information is still a bit dense and could do with further revision, I can't say I'll have time to tackle that.

It may just be easier to add a link to the README docs to this issue for more information in the meantime (similar to the approach taken for pre-release tags (semver/pep440) caveats).

If you've landed here from seeking a deeper understanding of config decisions/caveats with the action, you may also appreciate this resource on labels/annotations defaults.

---

Beyond the relevance of the priority attribute (especially if you have various tag types with a subset only being used between different trigger contexts of a workflow) do keep in mind:

• type=raw,value=latest,enable=false does not prevent the latest tag from being added by default. Configure the flavor input with latest=false to opt-out instead.
• There is a caveat that might not seem obvious initially that applies to mutable tags like the latest tag and semver styled tags (1.2.3 => :1, :1.2, :1.2.3) when your release process would update past major or minor version series with a new point/patch release (bug fix, security patch)
  • If you're not careful you'll mess up these mutable tags (:major + :major.minor) to resolve to these earlier release channels instead of the intended "latest" release channels.
  • I have provided some suggestions to deal with that at the expense of extra complexity. It would be better/simpler however to parameterize your workflow in a way that you have a better handle on managing the inputs for determining what the latest major and minor versions are.

The four tags that opt-in to latest tag (and the importance of the priority attribute)

#567 (comment)

---

Usage of any of these tags types will implicitly enable a latest tag as the docs explain when flavor.latest=auto would evaluate to flavor.latest=true:

• type=ref,event=tag (source: always true)
• type=semver,pattern=... (source: false if pre-release or invalid semver)
• type=pep440,pattern=... (source: false if pre-release or invalid pep440)
• type=match,pattern=... (source: always true)

NOTE:

• Those all rely on github.ref_type == 'tag' (a push event trigger from a tag rather than a commit), unless they were given an explicit value as input instead.
• latest will be determined by the first tags input entry processed by the action (which is dependent upon the sort order based on their associated priority attribute).
  • type=semver (900) / type=pep440 (900) > type=match (800) > type=ref (600)
  • When priority is the same value, the secondary sorting factor is the declaration order from the tags input.
  • If a different tag type from those four mentioned was given a higher priority (or already had higher by default, eg: type=schedule (1000)), then that tags default flavor.latest=auto logic is to set latest=false, preventing an implicitly added a latest tag.

Conditional logic for type=semver/type=pep440 on pre-release inputs:

#461 (comment)

---

metadata-action/src/meta.ts

Lines 183 to 198 in ed95091

	let latest = false;
	const sver = semver.parse(vraw, {
	loose: true
	});
	if (semver.prerelease(vraw)) {
	if (Meta.isRawStatement(tag.attrs['pattern'])) {
	vraw = this.setValue(handlebars.compile(tag.attrs['pattern'])(sver), tag);
	} else {
	vraw = this.setValue(handlebars.compile('{{version}}')(sver), tag);
	}
	} else {
	vraw = this.setValue(handlebars.compile(tag.attrs['pattern'])(sver), tag);
	latest = true;
	}
	return Meta.setVersion(version, vraw, this.flavor.latest == 'auto' ? latest : this.flavor.latest == 'true');

1. At the start of that snippet the latest variable is initially false and if the semver tag being processed is considered a release tag (not parsed as a semver pre-release version) it'll be set to latest=true.
2. Finally at the end of that snippet it'll check flavor.latest, which if configured as auto will use the latest variable (release: true, or for pre-release: false) that was set in the prior condition, otherwise it'll use what was explicitly configured on the workflow (flavor.latest=<true|false>).

Influence of flavor.latest on creating an implicit latest tag (compared to manual type=raw,value=latest,enable=<condition>)

#461 (comment)

---

I'm short on time, so here's a rough outline for anyone landing here, that may want to contribute a fix to the README:

• type=raw could mention a caveat with value=latest.
• The latest tag section references the default flavor.latest=auto behaviour.
  • That section then suggests using a type=raw tag with enable for controlling a conditional latest tag, without clarifying that the flavor.latest=auto default will disregard/override that enable logic.
  • Additionally if flavor.latest=true and a type=raw,value=latest,enable=true tag are both present, the tags output will produce two latest tags (even when there is no suffix/prefix difference involved).
• flavor setting describes the onlatest condition for flavor.<prefix|suffix>:

  • It is not clarified that onlatest attribute is only applicable to an implicit latest tag generated from flavor.latest=<auto|true> (when auto resolves to true). onlatest has no relation to an explicit type=raw,value=latest tag (which could easily be confused that it does).

  • onlatest is also false by default, but that's not documented either (see this recent bug report from a confused user).

  • flavor.suffix (and equivalent flavor.prefix) applies to all explicit tags, but can also be used as an attribute in tags to opt-out via ,suffix= (suffix unset via an empty value). This override behaviour could be documented more clearly, given the current docs that show a tag types implicit defaults which already include ,prefix=,suffix= it may not be obvious that you can opt-out of the flavor prefix/suffix this way.

    metadata-action/README.md

    Lines 703 to 708 in ed95091

    	Extended attributes and default values:
    	```yaml
    	tags: |
    	type=raw,enable=true,priority=200,prefix=,suffix=,value=
    	```