Why recommend `compose.yaml` over `compose.yml`?

[Download]

What is the problem you're trying to solve Prevent causing confusion and needlessly splitting up the filename space.

Describe the solution you'd like Be pragmatic and recommend compose.yml as the preferred filename for the compose file.

Additional context Currently this spec tells readers that the preferred filename for compose files is compose.yaml in the Compose file section:

Compose file

The Compose file is a YAML file defining version (DEPRECATED), services (REQUIRED), networks, volumes, configs and secrets. The default path for a Compose file is compose.yaml (preferred) or compose.yml in working directory. Compose implementations SHOULD also support docker-compose.yaml and docker-compose.yml for backward compatibility. If both files exist, Compose implementations MUST prefer canonical compose.yaml one.

However, you are currently in the spec itself, under section Extends giving as an example the filename common.yml, which is not in line with the extension you are recommending:

extends

Extend another service, in the current file or another, optionally overriding configuration. You can use extends on any service together with other configuration keys. The extends value MUST be a mapping defined with a required service and an optional file key.

extends:
  file: common.yml
  service: webapp

Also, you already have files in this repo using the .yml extension, again not in line with the spec's own recommendation:

• _config.yml

And the docker/compose repo also has files using the .yml extension over the .yaml extension:

• .golangci.yml

Also, Github Flavoured Markdown does not actually apply syntax highlighting when we use yaml in code fences, as testified in #151 :

foatslowly3 commented on 21 Mar 2021

github only apply syntax highlightin when we use yml, not yaml.

Originally posted by @ndeloof in https://github.com/compose-spec/compose-spec/pull/16#r366172417

So there seems to be some bias against yaml and in favour of yml in Github Flavoured Markdown.

To find some statistics for real world use, I looked at the number of Google Search results for "docker-compse.yml" vs "docker-compose.yaml":

• "docker-compose.yml": 1.790.000 results
• "docker-compose.yaml": 137.000 results

Hardly scientific, I know, but I think this still is a pretty strong lead that in real world use, the .yml extension is strongly preferred over .yaml, by about 13 to 1.

Finally, you have been leading by example in the Compose documentation as well:

Specifying multiple Compose files

You can supply multiple -f configuration files. When you supply multiple files, Compose combines them into a single configuration. Compose builds the configuration in the order you supply the files. Subsequent files override and add to their predecessors.

For example, consider this command line:

$ docker compose -f docker-compose.yml -f docker-compose.admin.yml run backup_db

The docker-compose.yml file might specify a webapp service.

So my conclusion is (and I am also seeing this in my personal experience with encountering compose files in projects) that currently, .yml is preferred by most over .yaml.

As an outside observer, I am witnessing that there are many outdated examples of compose files out there that are written for older versions of the compose spec. So recommending a new name for compose files written for the new spec is imho a good idea. It will help make it more clear what version of the spec people are targeting. However, right off the bat you are splitting up the filenames by recommending .yaml over .yml, when it seems that in practice people (even yourselves) seem to prefer .yml.

I understand that YAML is a separate spec and that maybe recommending .yaml logically follows from adopting this spec. But since it seems to conflict with real world use, you may want to reconsider and say that compose.yml is the canonical / preferred name and compose.yaml is a valid alternative.

You have to wonder, if even right here in the spec itself, you are breaking the recommendation to prefer .yaml over .yml, is it smart to recommend it? Will people actually follow the recommendation or will they follow your and Github's example and use .yml instead?

[EricHripko]

Hi @Download 👋 Thank you for sharing this feedback. Please note that the recommendation for Compose file names does not automatically apply to all YAML files. The files you highlighted don't contain any Compose definitions and are used for different purposes/with different tooling. You do make a solid point about current .yaml vs .yml usage. Looking at GitHub usages:

• docker-compose.yaml is at 173,795
• docker-compose.yml is at 1,335,159

@ndeloof @hangyan @justincormack @ulyssessouza what do you think?

[ndeloof]

The official recommended filename extension for YAML files has been .yaml since 2006.[12]

That's being said that's just a way for us to define order for searching files on disk, up to you to use your own conventions :)

[furkanmustafa]

3 letter shorthand for file extensions is a legacy msdos/windows/fat-fs limitation.

well, not just the extension, the filename is also limited to 8 chars in such systems, was called micros~1 if anybody remembers. Recommending .yml would come along with capping file names to 8 chars as well, if that is the concern.

Some projects indeed recommend that for maximum compatibility, I wonder which OSes are they thinking of :D (see: .gitlab-ci.yml)

As long as supported as a fallback, needs should be covered. It would be best to avoid recommending such thing and prolonging the legacy even further.

Github usage statistics above is also a side-effect of that legacy. Doesn't provide any convinience.

(Thankfully nobody is talking about making .jsons .jsn or something.. I wonder why)