reflect: do not deprecate Ptr APIs just yet

[mvdan]

In basically all of my modules, I support the two latest major Go versions - right now, this means 1.16 and 1.17.
I develop on Go master, for the sake of helping with testing and developing new features.

In one of the codebases that must still support Go 1.16, I got the following warning from staticcheck:

$ staticcheck ./...
cmd/shfmt/json.go:27:7: reflect.Ptr is deprecated: use the new spelling, Pointer.  (SA1019)
syntax/walk.go:269:7: reflect.Ptr is deprecated: use the new spelling, Pointer.  (SA1019)

Staticcheck is right: the type is marked as deprecated.
Unfortunately for me, this is a warning that will be bothering me for six to twelve months before I can fix it.
reflect.Pointer won't appear until Go 1.18, and I won't drop support for 1.17 until 1.19 comes out.

I think the standard library needs to at least wait one major release before formally deprecating APIs.
That is, the earliest we could deprecate reflect.Ptr would be in Go 1.19, when the majority of module authors can stop worrying about Go 1.17 and older.

Alternatively, to be extra conservative towards module authors who move slowly, we could make the general rule to wait two major releases.

I thought this rule was already common knowledge, as https://go-review.googlesource.com/c/go/+/284777/ was rejected for deprecating io/ioutil too early.
We seem to have dealt with the reflect API changes differently, though.
Perhaps this means we should write down this general standard library deprecation rule?

Marking as NeedsDecision for 1.18, as making a decision after 1.18 would be a bit late :)

cc @ianlancetaylor @bradfitz @rsc

[mvdan]

Oh, and CC @dominikh for staticcheck, though I'm still fairly sure that it's correct here. At least as long as deprecation notices don't carry Go version information.

[bcmills]

At least as long as deprecation notices don't carry Go version information.

See previously #38149.

[mvdan]

I'm going to mark this as a release blocker, because some time has passed and I fear it might go under the radar given all that's happening for 1.18. We definitely need to make a choice before 1.18 comes out, and ideally before the first beta is out as well.

[bradfitz]

I didn't realize tools would be so aggressive about this.

I'm fine tweaking the docs to a pattern recognizable to humans but not to tools for a few releases.

Want to send a change?

[randall77]

We'll need the same for CL 350691 which deprecated reflect.Value.Pointer.

[dominikh]

Oh, and CC @dominikh for staticcheck, though I'm still fairly sure that it's correct here. At least as long as deprecation notices don't carry Go version information.

FWIW, Staticcheck maintains a handwritten mapping of Go identifiers to 1) when they were deprecated 2) when their recommended alternative became available. As such, Staticcheck won't flag uses of a deprecated identifier if the user is targeting an older version of Go.

We usually update that mapping close to a Go release (either closely before or closely after...) and make a new release.

I thought this rule was already common knowledge, as https://go-review.googlesource.com/c/go/+/284777/ was rejected for deprecating io/ioutil too early.

Generally speaking, Go has always immediately deprecated things when alternatives became available. io/ioutil is the odd one out here.

[dominikh]

(as an aside, the reflect documentation still mentions Ptr and PtrTo in various places, such as in the documentation of New and UnsafePointer; someone should fix that)

[gopherbot]

Change https://golang.org/cl/358454 mentions this issue: all: use reflect.{Ptr,PtrTo}

[mvdan]

We usually update that mapping close to a Go release (either closely before or closely after...) and make a new release.

I see, I didn't know that. Would there be a way to not issue warnings for deprecations that haven't been released yet?

Generally speaking, Go has always immediately deprecated things when alternatives became available.

If that is our policy in a consistent way, then that's fine by me - as long as tools follow it as well. I shouldn't be getting warnings to fix my code before I am able to do so, even if I happen to be developing on tip.

[mvdan]

io/ioutil is the odd one out here.

Now I'm curious what makes ioutil special so that we should wait a few releases to deprecate it.

[dominikh]

I see, I didn't know that. Would there be a way to not issue warnings for deprecations that haven't been released yet?

A way for users right now? No. A way for me to change Staticcheck to behave that way? Trivially.

Now I'm curious what makes ioutil special so that we should wait a few releases to deprecate it.

Hm, seeing these messages, I'm not sure reflect.Ptr should be deprecated, either.

• https://go-review.googlesource.com/c/go/+/284777/1#message-f4c5090b3a565d8e28abfa2ab036ed29e94235da
• https://go-review.googlesource.com/c/go/+/284777/1#message-241c85847541f38f2ae44e61ef84eac2487508f5

/cc @rsc @ianlancetaylor