Deprecate -f flag from docker tag

[duglin]

Closes #9798

@maintainers please note that this is a change to the UX. We no longer
require the -f flag on docker tag to move a tag name from an existing image.
However, this does make us more consistent across our commands,
see #9798 for the history.

Signed-off-by: Doug Davis dug@us.ibm.com

[calavera]

I like consistency. Design LGTM.

[thaJeztah]

Yup, I like consistency as well, design LGTM

also /cc @tianon, who opened the issue that this resolves ❤️

[schmunk42]

Is there still a way not to move the tag of an image if the tag exists?
I liked the -f behavior very much, since I usually don't want to move a tag, same as with git.

[duglin]

@schmunk42 no, if we do this then we'll move it every time. Can you explain your scenario a bit? It sounds like you count on getting an error as part of your normal work flow - is that true? What do you do when you get the error to recover - just generate a new tag and try again?

[runcom]

LGTM+++

[duglin]

@schmunk42 Have you consider changing it so that you use docker images [tag] first to see if the name exists and then picking a new one if it does

[schmunk42]

@duglin Our workflow in some projects is to tag docker images on a release branch from a version-file.

Now, if someone accidentally pushes another commit with the same version on the release branch ... nothing happens, simply because the tag is already there.

I have something like this in our CI scripts:

VERSION=4.1.1
VERSION_MINOR=4.1
VERSION_MAJOR=4

docker tag ....:$VERSION
docker tag -f ....:$VERSION_MINOR
docker tag -f ....:$VERSION_MAJOR

btw: About consistency, I had opened a ticket to introduce -f here docker-archive-public/docker.machine#2349

I don't really rely on the error, but I also like to be asked, before I change crucial things.

What's about tagging an image during local development, then later I move the tag accidentally - how do I get back the original version?

[jessfraz]

LGTM

[bjaglin]

The docker tag -f behavior already changed in 1.4.0 (the flag semantics were not honored), which forced us to add this flag in our 150+ repositories build scripts to keep the CI builds idempotent.

Seeing that this flag will be removed in 1.12 makes me very sad since we will have to revert this change across all our repositories... I am OK with deprecation for consistency, but can't the actual removal happen in a major release (2.x)?

[runcom]

@bjaglin it will be removed in docker-1.12 so ppl should have time to update their stuff. For now you just get a warning

[schmunk42]

@bjaglin You're 100% on spot.

@runcom We will run into this issue, since we're using CI runners on different hosts, probably dozens at 1.12, we will need to detect the docker version and act accordingly.

[bacongobbler]

We also use -f to overwrite a tag in our build environment when generating images. @bjaglin's problem case is bang-on to our problem case as well.

I understand why -f is getting deprecated since docker tag is reverting to its old behaviour (yay!), but at the same time this is a major UX change which by semver's definitions should not be rolled into a minor release as it breaks the semver contract. Looking at the history of previous UX changes like the very change that introduced this behaviour, third party projects like Drone, Packer, Mesos and Deis have had to tweak things in the past because client UX changed.

I guess that also brings me to my question... What can we consider covered by a semver contract in docker if existing client features keep being broken in minor releases? A few examples of breaking changes in the client that have occurred would be when docker inspect output changed and the all-too-familiar --insecure-registry flag change. Is it safe to say that the client is to be considered semver-incompatible and the only thing covered by Docker's semver contract would be the remote API?

[duglin]

Given we haven't moved from "1.x" ever I don't think waiting for a major release version is much of an option. The best Docker has is the "give 'em 2 release warning": https://github.com/docker/docker/blob/master/docs/misc/index.md#feature-deprecation-policy

[tianon]

Yeah, the flag isn't _gone_ yet (your scripts should still work as-is), it's just turned into a warning now (and doesn't have any effect).

[outcoldman]

docs team please be more specific about the deprecation, right now when you use -f flag it says

Warning: '-f' is deprecated, it will be removed soon. See usage.

Ok, let's take a look on usage https://docs.docker.com/engine/reference/commandline/tag/, what it says about -f? Right, nothing.

So what is current behavior is? Does it force or not? Do I need to manually delete tag before using it? The only one way to find out is to actually find this deprecation commit.

It is always good to tell users, who used this before - what is the "migration" plan is.

[thaJeztah]

@outcoldman the deprecation is explained here; https://docs.docker.com/engine/deprecated/. The reason the flag is no longer mentioned on https://docs.docker.com/engine/reference/commandline/tag/ is because it's been deprecated; see this PR, which removes it from the docs

[outcoldman]

@thaJeztah great, but how I can get to this page? I'm not trying to argue about this deprecation, I am trying to point on the luck of documentation in usage/help, when the deprecation message says Warning: '-f' is deprecated, it will be removed soon. See usage..

[thaJeztah]

@outcoldman that message is automatically generated for flags that are marked deprecated; usually, a flag is deprecated in favor of another flag, and is a bit more informative;
https://github.com/docker/docker/blob/34a83f9f2c0516b3c5e7024393487eee54309401/pkg/mflag/flag.go#L25

If you're have a suggestion on how to improve that message, feel free to add.

[outcoldman]

@thaJeztah for example standard library always require you to specify a deprecation message, see https://godoc.org/github.com/spf13/pflag#FlagSet.MarkDeprecated (and https://github.com/spf13/pflag/blob/master/flag.go#L311) not something auto-generated, but informative for user.

This is just a suggestion.

[thaJeztah]

That's not the standards library; the standards library (https://golang.org/pkg/flag/) doesn't have a way to deprecate flags, hence the (slightly hacky) mflags package was created. I agree that a custom deprecation message could be nice, possibly replacing mflags with pflags could be an option, however, with the deprecation page, and a mention in the change logs, it's not our top priority; PRs welcome though

[tianon]

IMO it'd definitely be neat to adjust our flags package to allow for the deprecation message to be generally customized so we could add a link to our deprecation page 😇