Replace "tags" with "keys" in docs

Description

The way the docs talk about YAML is not quite right.

https://go-vela.github.io/docs/reference/yaml/#tags says:

A YAML document is compose of one to many key-value pairs where the key is called the tag and the value is evaluated to an explicit type (Int, Float, string, bool, etc), see YAML 1.2 spec for full details.

In YAML, the "tag" defines the type. So, an explicitly tagged document looks like this:

Block style: !!map
  Clark: !!str Evans
  Ingy: !!str döt Net
  Oren: !!str Ben-Kiki

Flow style: !!map { Clark: !!str Evans, Ingy: !!str döt Net, Oren: !!str Ben-Kiki }

Here, the tags are !!map and !!str. In practice, most YAML "tags" (which define data types) are implicit however, like this:

Block style:
  Clark: Evans
  Ingy: döt Net
  Oren: Ben-Kiki

Flow style: { Clark: Evans, Ingy: döt Net, Oren: Ben-Kiki }

So, when the vela docs call these things "tags", that is unique to Vela - they are not "tags" elsewhere. It would be better to call them "keys". Here are some example keys that are called "tags" in the docs when "key" would be more appropriate:

environment
version
metadata
- template
- clone
- render_inline
worker
- flavor
- platform
templates
- name
- source
- type
- format
services, steps
- name
- image
- pull
- secrets (step only)
- environment
- ruleset (step only)
- parameters (step only)
- commands (step only)
- template (step only)
- entrypoint
- detach (step only)
- ports (service only)
- volume (step only)
- ulimits
- privileged (step only)
- user
stages
- name
- steps (hmm. Docs say this is type []string which is wrong)
- needs
secrets
- name
- key
- engine
- type
- origin

When I started learning Vela, I was often confused by the use of "tags" in the Vela docs. it's taken a lot of effort to call stuff "tags" since that's what Vela seemed to call things. Then, I found that section of the docs that cites the YAML spec for calling things "tags". That was a misunderstanding of the spec, so I thought I'd raise this issue to clarify things.

Value

Accuracy (uhm in a nit-picky way 😛)

Definition of Done

Docs use the term "tag" correctly.

Effort (Optional)

not much. Probably most effort will be discussing it in this issue.

Impacted Personas (Optional)

docs users. people. me.

Here are some quotes from the YAML spec that should hopefully clarify things:

I'm using links to the latest spec version (1.2.2). They've changed their doc generator so the links look slightly different. For example https://yaml.org/spec/1.2/spec.html#id2761292 in the vela docs gets redirected to https://yaml.org/spec/1.2-old/spec.html#id2761292 (note the 1.2-old in the path). The equivalent in the latest spec is: https://yaml.org/spec/1.2.2/#24-tags

https://yaml.org/spec/1.2.2/#24-tags:

Explicit typing is denoted with a tag using the exclamation point (“!”) symbol.

https://yaml.org/spec/1.2.2/#3212-tags:

YAML represents type information of native data structures with a simple identifier, called a tag. ... Local tags start with “!”, are not URIs and are not expected to be globally unique. ... YAML tags are used to associate meta information with each node. In particular, each tag must specify the expected node kind (scalar, sequence or mapping).

https://yaml.org/spec/1.2.2/#332-resolved-tags:

Typically, most tags are not explicitly specified in the character stream. During parsing, nodes lacking an explicit tag are given a non-specific tag: “!” for non-plain scalars and “?” for all other nodes. ... YAML processors should resolve nodes having the “!” non-specific tag as “tag:yaml.org,2002:seq”, “tag:yaml.org,2002:map” or “tag:yaml.org,2002:str” depending on their kind.

https://yaml.org/spec/1.2.2/#tag-handles

The primary tag handle is a single “!” character. ... The secondary tag handle is written as “!!”.

https://yaml.org/spec/1.2.2/#691-node-tags:

A tag shorthand consists of a valid tag handle followed by a non-empty suffix. ...

Example 6.26 Tag Shorthands
---
- !local foo
- !!str bar

https://yaml.org/spec/1.2.2/#chapter-10-recommended-schemas:

Chapter 10. Recommended Schemas

A YAML schema is a combination of a set of tags and a mechanism for resolving non-specific tags.

Example tags under https://yaml.org/spec/1.2.2/#1011-tags:

10.1.1.1. Generic Mapping

URI tag:yaml.org,2002:map ...

Example 10.1 !!map Examples
Block style: !!map
  Clark : Evans
  Ingy  : döt Net
  Oren  : Ben-Kiki
10.1.1.2. Generic Sequence

URI tag:yaml.org,2002:seq ...

Example 10.2 !!seq Examples
Block style: !!seq
- Clark Evans
- Ingy döt Net
- Oren Ben-Kiki
10.1.1.3. Generic String

URI tag:yaml.org,2002:str ...

Example 10.3 !!str Examples
Block style: !!str |-
  String: just a theory.

Flow style: !!str "String: just a theory."

Example tags under https://yaml.org/spec/1.2.2/#1021-tags:

10.2.1.1. Null

URI tag:yaml.org,2002:null ...

Example 10.4 !!null Examples
!!null null: value for null key
key with null value: !!null null
10.2.1.2. Boolean

URI tag:yaml.org,2002:bool ...

Example 10.5 !!bool Examples
YAML is a superset of JSON: !!bool true
Pluto is a planet: !!bool false
10.2.1.3. Integer

URI tag:yaml.org,2002:int ...

Example 10.6 !!int Examples
negative: !!int -12
zero: !!int 0
positive: !!int 34
10.2.1.4. Floating Point

URI tag:yaml.org,2002:float ...

Example 10.7 !!float Examples
negative: !!float -1
zero: !!float 0
positive: !!float 2.3e4
infinity: !!float .inf
not a number: !!float .nan

ie: essentially, YAML tags are !!map !!seq !!str !!null !!bool !!int !!float.

go-vela / community