Rule: Consistent file extension

[mcandre]

THE YAML spec does not define what the file extension should be, and so there are various and sundry conventions for naming your YAML files. This makes it harder, for example, to identify all your YAML content files, because they can really be named anything, even omitting file extensions all together.

We can’t jump in and insist that all such files be renamed *.yml (or *.yaml) overnight, including templated YAML files like *.yml.erb and *.yml.gotpl. This would of course break a lot of software.

But I think it is time to lean to one preferred extension or the other. We could have a rule, off by default, that can express the desired extension. The rule would allow for suffixes, as long as . is infix in the basename.

Then it is much easier for yamllint itself to identify YAML files to lint, once we have a consistent file pattern. Any applications that currently expect their own names for YAML files, like .rubylintrc and the like, have the option of deprecating the y[a]ml-less name in favor of a *.y[a]ml name. Of course, the rule would then allow for such custom path patterns to be allowed, if desired.

That’s the long and short of it. It’s a small thing, but one that probably drives DevOps nuts (find is never the answer!)

[freddrake]

It's also not unusual for languages built on top of YAML (RAML being an example I use at times; there are plenty of examples out there) to have their own conventions for naming.

Having a rule that really makes sense seems dependent on application.

[adrienverge]

That's an interesting topic. It would be a bit technical, because currently yamllint rules are based on the contents of files.

@mcandre how would detect that a file has a wrong extension? More precisely, would you allow/forbid these:

• a file named noextension with YAML content?
• a file named file.txt with YAML content?
• a file named file.yaml with text content?

[mcandre]

For now, we can reduce the list of files assumed to be YAML:

• *.yml
• *.yaml
• *.yml.*
• *.yaml.*
• Any special filenames such as .yamllint

All other files would be reasonable to assume as not YAML. It's up to developers to either apply a basic YAML file extension to their files, or inform the yamllint project of their snowflake filename for consideration for inclusion in the list of yamlish file patterns.

[ferrarimarco]

Also, apparently YAML recommends the .yaml extension 😄

[scop]

.yaml seems to be the "best practice" indeed, if any.

• https://yaml.com/faq/
• https://yaml.org/faq.html
• https://www.yaml.info/learn/bestpractices.html#file
• https://en.wikipedia.org/wiki/YAML#cite_ref-12

None of these feel that "authoritative" though. The yaml.org and .com are from "the" YAML organisation, but the FAQ doesn't seem to be currently linked from the main yaml.org page. Anyway, good enough to recommend .yaml IMHO :)

[adrienverge]

Everyone agrees .yaml is better than .yml, I do too!

However the question is what to do, on which files?

• file.txt with YAML content:
  → don't report anything (that's yamllint current behavior already ✔️)
• file.yaml with text content:
  → report YAML errors (that's yamllint current behavior already ✔️)
• file.yml:
  → complain that extension should be .yaml (not current behavior 🟠)
• file.yaml.j2:
  → don't do anything (that's yamllint current behavior already ✔️), because .yaml.j2 is a valid extension (Jinja 2), and because contents should not be linted (it's not valid YAML and isn't parsable, see Clarify 'disable-line' and parser errors #463 for example)
• file.yml.j2:
  → don't do anything (that's yamllint current behavior already ✔️), because why *.yml.j2 should create an error, but not .yml.jsn.txt or c.yml.ing or cymling?

So in the end, such a new rule would be summarized to a simple:

find -name '*.yml'

[shanike]

I'm looking for a lint to do this exact check:
Enforce a consistant yaml file extension: yaml XOR yml. (Personal preference: yaml)

Any update on adding it to yamllint?

[mcandre]

I propose .yaml (lowercase) as the one true file extension. It's a one to one match with the language name. This isn't 1980 where DOS is limited by the length of the filename.

Google engineers can look elsewhere. No one cares about shaving off a single byte. They're using binary formats anyway.

Mind, we need a way to temporarily permit deviations. Because applications that use YAML for configuration often historically goof the extension and require .yml, or explicit flags, in order to launch properly.

App maintainers can deprecate .yml, eventually allowing yamlllint users to remove the rule exceptions over time.