Yamllint: Difference between revisions
No edit summary |
link to github action workflow for yamllint in the Meza repo |
||
| (2 intermediate revisions by the same user not shown) | |||
| Line 3: | Line 3: | ||
Use an online validator like https://www.yamllint.com/ or https://jsonformatter.org/yaml-validator | Use an online validator like https://www.yamllint.com/ or https://jsonformatter.org/yaml-validator | ||
Of course, you should have one in your local tools and CI pipeline to ensure that your [[YAML]] is always correct. With <code>yamllint</code>, there is both a script and a Python module; meaning you can write your own linting tool in Python by invoking (importing) the yamllint module<ref>https://yamllint.readthedocs.io/en/stable/development.html</ref>. See the caveat section below about "using the right tool for the job" - meaning use the right linter for the language/project you are linting. | Of course, you should have one in your local tools and [https://github.com/freephile/meza/blob/e4ba295c4705ba982ae3b5c100ce212d366c1330/.github/workflows/yamllint.yml CI pipeline to ensure] that your [[YAML]] is always correct. With <code>yamllint</code>, there is both a script and a Python module; meaning you can write your own linting tool in Python by invoking (importing) the yamllint module<ref>https://yamllint.readthedocs.io/en/stable/development.html</ref>. See the caveat section below about "using the right tool for the job" - meaning use the right linter for the language/project you are linting. | ||
{{Notice|If you have a <tt>.yamllint</tt> file in your working directory, it will be automatically loaded as configuration by yamllint.}} | {{Notice|If you have a <tt>.yamllint</tt> file in your working directory, it will be automatically loaded as configuration by yamllint.}} | ||
| Line 10: | Line 10: | ||
==Manually fix errors== | ==Manually fix errors== | ||
Unfortunately, <tt>yamllint</tt> does not fix your file for you. There could be ambiguities about the proper fix, so you need to do the fix(es) yourself. | Unfortunately, <tt>yamllint</tt> does not fix your file for you. There could be ambiguities about the proper fix, so you need to do the fix(es) yourself. | ||
== VSCode settings == | |||
I had a problem with VSCode automatically re-introducing spaces around curly braces - causing the very same yamllint errors I was trying to fix. Despite trying various linters (aka formatters), I ultimately found that the only way to be able to save the correct formatting was to '''disable''' <code>formatOnSave</code> in my user settings. This was because the "default settings" (<code>/defaultSettings.json</code>) was read-only so I could not change it, AND it was configured to <code>formatOnSave</code> - using the kennylong linter which is apparently bad for yaml outside kubernetes contexts. | |||
In VSCode, use <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> to open the preferences dialog and type 'Preferences: Open User Settings' then open User Settings (JSON) settings. Ensure you have lines like this (especially the editor.formatOnSave line because I tried other linters like "redhat.vscode-yaml" without success):<syntaxhighlight lang="json"> | |||
"[yaml]": { | |||
"editor.defaultFormatter": "kennylong.kubernetes-yaml-formatter", | |||
"editor.autoIndent": "advanced", | |||
"editor.formatOnSave": false | |||
}, | |||
</syntaxhighlight> | |||
==Cheatsheet== | ==Cheatsheet== | ||
| Line 38: | Line 49: | ||
== Yaml multiline == | == Yaml multiline == | ||
Interactive demonstration of Block scalars and Flow scalars https://yaml-multiline.info/ | <blockquote>When writing YAML in your [[Ansible]] playbooks, you run across values that span multiple lines using <code>|</code> or <code>></code>. Spanning multiple lines using a “Literal Block Scalar” <code>|</code> will '''include the newlines''' and any '''trailing''' '''spaces'''. Using a “Folded Block Scalar” <code>></code> will '''fold newlines to spaces.''' It is used to make what would otherwise be a very long line easier to read and edit. In either case the ''indentation (leading spaces) will be ignored''. </blockquote>from [https://docs.ansible.com/ansible/latest/reference_appendices/YAMLSyntax.html YAML in Ansible] (Community Documentation) | ||
Interactive demonstration of '''Block scalars''' and '''Flow scalars''' https://yaml-multiline.info/ | |||
[https://stackoverflow.com/questions/3790454/how-do-i-break-a-string-in-yaml-over-multiple-lines/21699210#21699210 The SO answer that describes them all] | [https://stackoverflow.com/questions/3790454/how-do-i-break-a-string-in-yaml-over-multiple-lines/21699210#21699210 The SO answer that describes them all] | ||
==Many linters== | ==Many linters== | ||
You can't just use "one" solution either<ref>https://phabricator.wikimedia.org/T95890</ref>. The leading GPL linter is based on Python, so depending on your code repo, you may instead want to use a JavaScript or PHP implementation. Thus, tools like [[wp:Grunt (software)]] may be used to automate JSHint linting in [[JavaScript]] projects<ref>https://www.codereadability.com/jshint-with-grunt/</ref>. | You can't just use "one" solution either<ref>https://phabricator.wikimedia.org/T95890</ref>. The leading GPL linter is based on Python, so depending on your code repo, you may instead want to use a JavaScript or PHP implementation. Thus, tools like [[wp:Grunt (software)]] may be used to automate JSHint linting in [[JavaScript]] projects<ref>https://www.codereadability.com/jshint-with-grunt/</ref>. | ||
| Line 59: | Line 63: | ||
*https://www.redhat.com/sysadmin/check-yaml-yamllint | *https://www.redhat.com/sysadmin/check-yaml-yamllint | ||
* https://www.redhat.com/en/blog/ansible-lists-dictionaries-yaml | * https://www.redhat.com/en/blog/ansible-lists-dictionaries-yaml | ||
* [https://symfony.com/doc/current/reference/formats/yaml.html YAML in Symphony] | |||
* [https://yaml.org/spec/1.2.2/#scalars YAML 1.2.2 spec on '''scalars'''] | |||
* [https://yaml.org/spec/1.2.2/#8112-block-chomping-indicator YAML 1.2.2 spec on '''block chomping'''] | |||
{{References}} | {{References}} | ||