Mention Docker 19.03 and its compose file version - and add max_repli…

[SvenDowideit]

it looks to me like 19.03's effect on swarm more compose wasn't documented.

this is an attempt at starting

[thaJeztah]

I think the reason for this would be that docker-compose (stand-alone, so not docker stack deploy) did not yet have support for the 3.8 spec. This was merged into compose master in docker/compose#7217

[SvenDowideit]

that really makes no sense - the 19.03 docker release supported a set of functionality that uses 'version: 3.8' - and there are many compose file things that aren't supported in docker-compose.

I'm hoping that whoever is the release manager for 20.03 also has responsibility to make sure that all features that are in that release, are sufficiently documented .....

[thaJeztah]

I agree it's a bit hairy; both the docker cli and docker-compose use the compose-file format, but the "compose file reference" section here is part of the compose docs. The intent was to have both compose and the docker cli be "in sync" w.r.t. the schema that's supported, but compose lagged behind on the 3.8 schema; the compose_file_v3 variable is used in the docs to set the version in all examples, so updating it right now would break those examples for docker-compose users.

As to the general issue of the spec being maintained in both locations; ideally, the compose file specification would live in a separate repository (the format is now used by various projects, so having a canonical location for the specification would be good); there's a tracking issue for that here; docker/compose#2089. For documentation, ideally it would be possible to generate the docs directly from the schema (docker/cli#1058) but so far I haven't found a proper solution for that (@SvenDowideit if you run into something that works well for that, I'm all ears 😅)

I'll check with @ulyssessouza and @ndeloof to see if a new version of compose with support for the 3.8 schema can be released soon, to unblock this PR.

[ndeloof]

3.8 is on it's way into docker-compose: docker/compose#7217

About schema being duplicated, see docker/compose#7047

[SvenDowideit]

think of it this way - for the last 9+months, the compose file docs have been broken for swarm users, as the v3.8 format was released then. The sad reality that docker-compose lagged in its support doesn't change the fact that v3.8 was released a long time ago.

[SvenDowideit]

so to quote @ndeloof from 7047:

Docker Compose schema on https://github.com/docker/cli/tree/master/cli/compose/schema/data is considered by maintainers as the leading one, and should be the place we use to any proposal for schame enhancements.

that really strongly suggests that the documentation should also deal with that information, and not block on the secondary docker-compose version.

the "updating it right now would break those examples for docker-compose users" just goes to show how utterly broken things are - examples shouldn't autoupdate to use the latest version, they should really indicate the minimum version that the example is tested for.... which also would show the user how old that feature is, and that it may well be stale.

[ulyssessouza]

@SvenDowideit LGTM.
It just needs a rebase.

[thaJeztah]

I rebased; should be good to go now 👍

[usha-mandya]

Thank you.

[netlify]

Deploy preview for docsdocker ready!

Built with commit d5e7a26

https://deploy-preview-10273--docsdocker.netlify.app

[netlify]

Deploy preview for docsdocker ready!

Built with commit d5e7a26

https://deploy-preview-10273--docsdocker.netlify.app