x/playground: 1.16 not available

[kevburnsjr]

What version of Go are you using (go version)?

go1.15.8

Does this issue reproduce with the latest release?

No.

What operating system and processor architecture are you using (go env)?

Not relevant (documentation issue)

What did you do?

Click "Run" on the filepath.Walk example on golang.org
https://golang.org/pkg/path/filepath/#Walk

What did you expect to see?

The output

What did you see instead?

A build error

prog.go:5:2: package io/fs is not in GOROOT (/usr/local/go-faketime/src/io/fs)

Conclusion

The system running golang.org's documentation examples should run the examples using the same version of go for which the examples were written.

[dmitshur]

Thanks for reporting.

CC @golang/release.

[dreamerjackson]

@dmitshur can you help merge it? thanks

[gopherbot]

Change https://golang.org/cl/294609 mentions this issue: fix: file walk example 1.16 not available in playgroud fix #44389

[kevburnsjr]

Should documented examples maintain backward compatibility wherever possible?

I created this issue after spending a lot of time googling for Go 1.15 documentation to find a WalkFunc signature that worked with the version of Go I was using. I never found it. I've been working with go for 8 years and I've never needed to do this before. I had to go to the 1.15 source code to find the correct syntax.

While forward compatibility is the primary reason for aliases to exist, should the privilege of backward compatibility not extend to the documentation of previously existing examples within a major point release?

I believe @dreamerjackson's approach (reverting the docs) is correct.
De-aliasing os to io/fs in existing method signatures (WalkFunc) and examples (Walk) in a way that causes their documented use to no longer work in older versions of the language should be considered a breaking change.
De-aliasing of existing exported symbols and documentation should be reserved for major point releases.

Reverting all instances of fs.FileInfo to os.FileInfo in all examples would require a few more changes. See 7bb721b

• https://golang.org/pkg/os/#example_FileMode
• https://golang.org/pkg/net/http/#example_FileServer_dotFileHiding
• https://golang.org/pkg/errors/#example_As
• https://golang.org/pkg/errors/#example_Is

[seankhliao]

pkg.go.dev has docs for past versions of the stdlib: https://pkg.go.dev/path/filepath?tab=versions
redirecting golang.org/pkg is #44356

[ianlancetaylor]

By the definitions used by the Go project, this is not a breaking change, because the code that worked with 1.15 continues to work fine with Go 1.16. The problem here is that code that works with Go 1.16 does not work with Go 1.15. And, of course, that is always true for every new release: code that works with the new release does not work with the old release.

I don't agree that we should change the Go 1.16 docs to work with Go 1.15. If you are using Go 1.15, use the Go 1.15 docs.

But for documentation and code that is maintained outside of the Go release process, then I agree that that documentation should continue to work with Go 1.15 as long as 1.15 is supported.

[toothrot]

The Playground Dockerfile needs an update to work with Go 1.16, due to assumptions it makes about GOPATH behavior for old tour snippets. This prevented the playground from updating with this release, and is why the newer demo code doesn't work.

I'll take a look.

[gopherbot]

Change https://golang.org/cl/295649 mentions this issue: all: support Go 1.16 in the Go Playground

[toothrot]

Fixed and deployed.

[kevburnsjr]

Confirmed, tyvm!