clarify v2 vs. v3 compose file format for different use cases

[BretFisher]

TL;DR

I'd like to use this PR to talk about how we can improve docs for helping people choose either compose file format versions 2.x vs. 3.x. I'm willing to add/change the messaging to help direct people to the correct version for their use case, and this may need to be tweaked in multiple files, but I'd like to get feedback on the right approach and docker team(s) strategy.

@garethr @shin- @thaJeztah (maybe others)

Brief History of Compose Version Usage:

• We were all happy in our 2.x days and then Swarm Mode came along and needed some new compose file concepts that wouldn't work in docker-compose cli. It made sense to create a new major version because many Swarm concepts wouldn't work in a single-daemon docker-compose scenario. 3.x was born, and it was awesome.
• We all starting changing every compose file to 3.x thinking that was the future for everything and a total superset of compose file features. New files started with version: 3.1 in early 2017
• Then SwarmKit didn't get all the features that docker run had and we needed some things in docker-compose that weren't yea in Swarm, so then 2.x was re-born with 2.2 (or 2.1 I can't remember,) and it was useful, but the choice became confusing between 2.x and 3.x.
• Messaging still said "we recommend 3.x" and our demos and tools were all still changing to 3.x. Today the common understanding in my workshops, weekly online chats, and online students are "2.x is old, always use 3.x" but the featureset doesn't match that sentiment.
• What I've been trying to communicate through 2018 is that 2.x lives on, as a featureset for people only using the file with docker-compose cli and don't intend to use that compose file with Stacks. 2.x has device support and now "healthcheck aware depends_on" which makes it useful as a separate version fork from the 3.x track which seems focused on multi-node orchestration compatibility.

The Problem

The problem is those feature differences are not being talked about much, and this PR is suggesting what might need to be the first of multiple file changes to help educate users on when they should choose 2.x or 3.x for a specific compose file.

When Swarm Mode and 3.x was released, many of us tried to use the "one compose file to rule them all" approach and for various reasons, I don't think it stuck. Even .env options, overrides, and templating was not enough to create a single-file experience for dev->test->prod. Too many things like multi-value compose arrays, complexities of dev vs. prod, and version differences have created a world where most teams, including docker's own examples, use docker-compose.yml for docker-compose local dev, and docker-stack.yml for Stack deployments. Honestly, this is fine, and not something I'm worried about.

But the value of 2.x versions and their features since 1.12 release is lost on everyone I meet IRL and online. There's no message that "2.x is of value and should still be used in certain use cases."

The Fix

My assumption is that this is what the current strategy is, and I'd like to help clear it up in docs:

• 3.x is focused on Stacks, with as much backward compatibility as docker-compose cli can support.
• 2.x is focused on docker-compose workflows and docker run features, with as much forward compatibility as stacks can support.

If this is the case, then what other things besides this small PR file change can support helping people chose their version. Should we have a separate "2 vs. 3" file linked from the main compose files? What other ways can I help make this strategy plain to the compose user?

Thanks for your help.

[GordonTheTurtle]

Deploy preview for docsdocker ready!

Built with commit a88f3db

https://deploy-preview-7593--docsdocker.netlify.com

[ushuz]

Make sense to me.

[thaJeztah]

ping @shin- ptal

[thaJeztah]

@BretFisher @shin- perhaps we should have a longer description of the differences between V2 and V3 in the documentation; also mentioning that the V2 spec is not "frozen", so features are still added to V2 (that may not be in V3). This leads to quite some confusion; docker/cli#1177

[BretFisher]

I added some details to the v1/2/3 summary lines, but wonder if this is enough.

• What other areas deserve a mention that v2 is still maintained/useful?
• Does this deserve a full "v2 or v3" heading on that page right below my edits, where we link to features that distinguish each branch?
• are their limits of v2 for single-machine dev/test that I'm not seeing? Any arguments for using v3 if you're not using Stacks?

[ahh-docker]

@shin- PTAL. Thanks!

[shin-]

On the technical aspect I think this is all accurate. As with #7525 I think this needs to be reviewed by @garethr though.

[yancyknight]

I just happened upon this issue while researching the difference between v2 and v3 and found the clarifications to the docs very helpful. Is this still being considered?