Standardize yaml formatting

[Sorin Sbarnea]

YAML formatting does interest us from two points of view:

• ansible-lint rules and its upcoming reformatting feature
• consistency of formatting of files from within devtools repositories

The goal is to find a set of rules to follow that are playing nice with most tools we identify as dumping yaml or popular reformatters.

3rd party tools identified so far, ordered by popularity:

• prettier (reformatter)- 41800⭑
• yamllint (linter) - 1800⭑
• pyyaml (library) - 1700⭑
• redhat.yaml (vscode-extension) 390⭑
• ruamel.yaml (library) - can load and save yaml, keeps comments, acts as a formatter, configurable to some extent. (no github presence)

Identified conflicts

yamllint inline comment indentation

It seems that yamllint default settings requires a two character space before inline comments, something that was inspired from Python world.

We were not able to find any formatter that can be able to produce, even with configurable options.

Luckily for us, we yamllint can be configured to disable this check. Next release of ansible-lint will include this change (already merged to main).

yammlint document-start

Default settings of yamllint are to require document-start but most reformatters do not add this by default. For example we disabled that in ansible-lint as requiring it was adding unneeded noise.

In almost two decades of using it, I still failed to find one place where this was needed. While fully aware of multi-document support, I still never found a place where this was used.

end of document marker

... at the end of documents, that is even less known feature. I failed to find any reason for adding it to any document.

[Bradley A. Thornton]

Thanks Sorin, this is great.

Once we sync up the formatting of yaml files, we should probably base our representation of yaml on that. Anytime we generate or show yaml, it should follow the same pattern. I know at least one case...... ansible-navigator, by default, adds the document-start

 0│---
 1│current: false
 2│default: false
 3│description: If you have cowsay installed but want to avoid the 'cows' (why????),
 4│  use this.
 5│env:
 6│- name: ANSIBLE_NOCOW

[Sorin Sbarnea]

@cidrblock It worth mentioning that we may not want to impose all rules, especially from start. For example I was considering ignoring the --- as a start. On the other hand, I want to be sure that whatever the editor caused reformatting is never in conflict with our rules.