Molecule: Remove first line `---`

[lucendio]

Proposal: Remove --- from the top of each YAML file, if it does not start with a front matter block

Author: Your Name <@lucendio>

Date: 2019-09-01

• Status: New
• Proposal type: file syntax
• Estimated time to implement: 2 days

Motivation

One way to use Molecule is to start by generating a skeleton. This results in a lot of files starting with a line that is not needed in most cases.

Problems

This first line (---) is unnecessary in most cases and can lead to confusion by the reader as well as to inconsistency in the project where Molecule generates code into.

Solution proposal

Remove the first line consisting of --- from each YAML file that does not start with a front matter or contains multiple YAML documents.

Dependencies

Possibly the (version of the) YAML parser being used by Ansible.

Testing

Use existing test facilities to see if something breaks.

Documentation

Probably referring to Ansible Docs: YAML Syntax, which states that this line is optional.

Anything else?

N/A

[ssbarnea]

I agree that --- is almost always useless. The question if if you can find a way to configure our yamllint lint to spot it and to prevent regressions. Please have read of https://github.com/adrienverge/yamllint/issues/302

[greg-hellings]

So is the recommendation to remove --- from the start of the cookiecutter templates? I keep them out of my own by having my own scenario templates and putting

  document-start:
    present: false
    level: error

into my yamllint configuration file. That configuration forces yamllint to throw an error when they're present. Perhaps a similar configuration could be used to keep them out of our files, here?

[cognifloyd]

Odd. I have always made sure that --- is in all my yaml documents. I like the consistency across all files. If I don't see the --- then I have to double check the line number to see if I'm at the top of the file or check my history to make sure I didn't inadvertently delete it.
It's interesting to see when opinions differ :smile:

[konstruktoid]

Agreeing with @cognifloyd here, but looking at it more practically I'm following the default yamllint rules and adapt the documents accordingly, otherwise I'd have eternal bike shed discussions.

But as a reference:

Looking at the spec:
https://yaml.org/spec/1.2/spec.html#id2760395:
"YAML uses three dashes (“---”) to separate directives from document content. This also serves to signal the start of a document if no directives are present. Three dots ( “...”) indicate the end of a document without starting a new one, for use in communication channels."

https://yaml.org/spec/1.2/spec.html#id2800967:
"A bare document does not begin with any directives or marker lines. Such documents are very “clean” as they contain nothing other than the content. In this case, the first non-comment line may not start with a “%” first character."

Ansible Galaxy (https://github.com/ansible/galaxy/blob/devel/galaxy/importer/linters/yamllint.yaml):
document-start: disable

Ansible (https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html#yaml-basics):
"All YAML files (regardless of their association with Ansible or not) can optionally begin with --- and end with .... This is part of the YAML format and indicates the start and end of a document."

¯_(ツ)_/¯

[ssbarnea]

Can is a very dangerous option as it creates a divergence point. I would like to ask Ansible team to make a decision and replace it with a should include or should not include, as this at least will help us make a decision. Based on previous interaction, I am almost ready to bet the answer will be a refusal to make a recommendation (i remember that I asked on irc few years ago, but i doubt the opinion changed).

[lucendio]

@ssbarnea so, what was their answer? What is your conclusion that led to closing this one?

[ssbarnea]

Is not molecule goal to make decisions about this. Ansible-lint and yamllint are projects more suited to make decision in this area.

I personally am in favour of not using --- when is not needed, but I am in a position to impose my preference.