docs/misc: update to align with Docker Compose v2

[georglauterbach]

Description

Align with upstream Docker Compose (v2). See #3289 (comment). @polarathene pinging you here just so you know. I don't want to merge this without any maintainer knowing first. Hence, pinging @casperklein here too. Marked for v13.0.0 because I consider this to be breaking.

Type of change

• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code

[polarathene]

LGTM 👍

• May want to use upstream preferred compose.yaml convention.
• May want to revise a comment regarding volumes_from.

[georglauterbach]

I also added a short note about the new Docker Compose V2 specification at the top of the Usage page.

[polarathene]

Nice! 😁

[georglauterbach]

INFO: Marked this with meta/feature-freeze now to indicate this PR is not to be merged before v12.1.0 is released.

[casperklein]

I am unsure about the renaming of docker-compose.yaml to compose.yaml. I've looked around and couldn't find any other projects using compose.yaml.
docker-compose.yaml is not deprecated, well-know and I don't think it will go away anytime soon. To avoid confusion, I would keep the old file name for now.

[polarathene]

I am unsure about the renaming of docker-compose.yaml to compose.yaml. I've looked around and couldn't find any other projects using compose.yaml.

Just in case you missed them, I unresolved the earlier review feedback for visibility. It quotes Docker docs that from July 2023 they're encouraging compose.yaml as the preferred convention.

Other projects may not be aware of that, or may not see any reason to adjust. You'll likely see a mix with time, we can do our part, but it's not mandatory.

---

docker-compose.yaml is not deprecated, well-know and I don't think it will go away anytime soon. To avoid confusion, I would keep the old file name for now.

We have had confusion over dropping the version field (here's a recent example from a user with Debian Bullseye), but that hasn't stopped us even though the version field is optional and wouldn't cause breakage to have kept?

Once Docker updates their docs later this year, they'll be using compose.yaml and presumably with newer distro releases docker-compose will more commonly be used as V2 docker compose. New guides online for Docker will probably start using the new V2 conventions, and then we introduce added confusion to anyone new to Docker?

Up to you, but as long as our docs make mention about V2 along with changelog / release notes announcement, I don't see the confusion concern being relevant as it'll apply to different users regardless. Aligning with Dockers documented usage makes the most sense and something we would transition to at some point anyway.

We get various issues / PRs to "fix" support for versions of compose that are over 3 years old that latest releases like Debian package. You will probably experience the same either way with this change.

[georglauterbach]

I'm definitely in favor of merging this as well. I think we should be up-to-date with our main container runtime. And users having issues with this due to using outdated packages is nothing new, and IMO no reason not to update :)

[github-actions]

Documentation preview for this PR is ready! 🎉

Built with commit: df18fd1