YAML formatting not compliant with yamllint "spaces before comments" requirement

[leosh64]

Describe the bug

yamllint, a linter used by many projects and companies, has a different requirement on the number of spaces before comments than what the YAML formatter in this plugin provides:

What yamllint requires is two spaces before the comment #:

    timeout: 1800  # value in seconds ~ 30m

Formatting of this plugin results in a single space:

    timeout: 1800 # value in seconds ~ 30m

Thus, YAML files saved (with Format on Save activated) with VS Code and this plugin enabled results in YAML files that are rejected by systems using yamllint to check for compliance (e.g. CI systems).

Expected Behavior

Files are formatted according to the yamllint requirements, e.g. double space before comments.

OR

Option to specify formatting requirements is given.

Current Behavior

Files are not formatted according to yamllint requirements, e.g. single space before comments.

Steps to Reproduce

• Create file test.yaml with contents:

- job:
    name: some-job
    timeout: 1800  # value in seconds ~ 30m

• Run yamllint test.yaml --> pass
• Apply formatting in VS Code which will reduce double-space to single-space
• Run yamllint test.yaml --> fail

Environment

• Windows
• Mac
• Linux
• other (please specify)

[tumido]

Hey! So I've digged this rabbit hole...

1. YAML for VSCode uses Prettier so we first need support for this in Prettier. Please 👍 on this PR if you can: [YAML] Allow to set amount of spaces between comments and content prettier/prettier#10926
2. We can update Prettier and enable the flag in here (feat(prettier): Support doNotIndent and commentSpacesFromContent #519, feat(prettier): Support doNotIndent and commentSpacesFromContent yaml-language-server#471)

[y120]

prettier has signalled intent to reject the linked PR. Is using a different formatter an option? This makes vscode-yaml unusable for me.

[MarkusTeufelberger]

Same here, I installed the Ansible VS Code extension and now my CI breaks if I use the (default-on!) YAML formatter. Completely disabling it is also not very nice, but apparently necessary. As this is apparently known for over a year, I really wonder why it still happens that a YAML extension creates YAML files that don't pass the most basic linter out there (yamllint).

Personally I also prefer the "2 spaces before inline comments" style by the way, so please fork prettier or use a different formatter (optionally, if necessary).

[ssbarnea]

I am pretty sure we will not fork prettier to add this (maintenance efforts are huge, this being only one of the issues). In the end I had to personally change ansible-lint defaults in v6 to match prettier and diverge from older yamllint defaults.

I know very well that black has a two-chars before comment, and that was likely the reason why yamllint opted for the same default.

While talking with others and trying to explain why two spaces are better instead of one, I discovered that on YAML there is not really a need for this, or at least is considerably lower than on python. On python it was problematic especially on long lines or lines that had expressions, but on yaml you usually don't have this. The coloring also helps distinguish the lines. Most of yaml comments are not inline and are before the affected line.

The practical workaround for this problem is to add one line to your yamllint config, like https://github.com/ansible/ansible-lint/blob/main/src/ansiblelint/yaml_utils.py#L54

[MarkusTeufelberger]

Well, that workaround would then break on every single file that wasn't made prettier...

I also disagree about the single space, I prefer the slight offset. To be pedantic, even the YAML spec only mentions "white space characters" (note the plural!) for comments: https://yaml.org/spec/1.2.2/#66-comments
Python code can also be colored and non-inline comments are out of scope anyways.

Well, I guess either there needs to be a better autoformatter than prettier for this extension or the shortcomings of prettier need to be better documented (such as requiring a custom yamllint config everywhere it is used). I also found it weird that prettier seems to have no opinion regarding boolean values by the way compared to the schemas for ansible (but not ansible-lint).

[ssbarnea]

@MarkusTeufelberger you forgot that prettier is not a linter, it is just a formatter. If you do not like its behavior I would invite you to raise a bug with it.

Based on popularity of prettier (42k stars) versus yamllint (1.9k) and the fact that this project has zero python code in it, I would say that what yamllint does by default, does not matter so much.

On the other hand we do have an example where yamllint (sole) maintainer refused to use indented sequences in its default settings, even if they are more popular around. So you do already have to change yamllint config if you want to also use it.

Keep in mind that this extension has nothing to do with Ansible or Python. Shortly if you don't like its formatting, disable it. I doubt we see a change in this area on the foreseeable future, especially as I am aware of far more pressing bugs that need to be addressed.

[linceaerian]

Hello, not a definitive solution but a workaround to use "prettier" format with https://yamllint.readthedocs.io/en/stable/rules.html#module-yamllint.rules.comments

• Create a .yamllint
• Add a custom rule:

 comments:
    min-spaces-from-content: 1

It will do the job of "not breaking the yamlint" but will still use a spacing of 1.