hash/maphash: Document whether used hash algorithm is stable across future versions

[nightlyone]

The new hash/maphash package in Go 1.14 doesn't make any statement about whether the hash results can differ in future versions or not.

At worst people will just assume they won't differ and store those hash values expecting to be able to repeat the hashing given the same values and seeds in the future.

I would sleep better when this was made more explicit in the documentation.

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

$ go version
go version go1.14beta1 linux/amd64

Does this issue reproduce with the latest release?

yes

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

go env Output

$ go env
GO111MODULE=""
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/me/.cache/go-build"
GOENV="/home/me/.config/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/me/sources/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/snap/go/4962"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/snap/go/4962/pkg/tool/linux_amd64"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/user/1000/go-build057059169=/tmp/go-build -gno-record-gcc-switches"

What did you do?

Read documentation of new package https://tip.golang.org/pkg/hash/maphash/

What did you expect to see?

Documentation on whether the hash function will always deliver the same hash across all Go 1 versions in the future given the same seed and bytes to be hashed.

What did you see instead?

No statement whether I can assume this or not.

[martisch]

I agree this should be called out in the packages documentation.

As this is using the runtime hash which has different implementations (non-AES vs AES) it can differ even using the same binary depending on cpu feature detection. It seems https://golang.org/cl/205069 dropped this part of the documentation which outlines that hashes are not even guaranteed to be equal between processes using the same binary:

// Two Hash instances with the same seed in different processes are
// not guaranteed to behave identically, even if the processes share
// the same binary.

@randall77 @rsc

[randall77]

It now says:

// Each Seed value is local to a single process and cannot be serialized
// or otherwise recreated in a different process.

There's no way to transfer a seed between processes (including the same binary across time).
So you can't observe a different algorithm because you can't use the same seed.

[nightlyone]

@randall77 Repeating such a statement in the packages overview section and maybe the relevant release notes section might help setting the expectations straight in more prominent places.

[gopherbot]

Change https://golang.org/cl/218297 mentions this issue: hash/maphash: mention that hash values do not persist in package docs

[gopherbot]

Change https://golang.org/cl/255968 mentions this issue: hash/maphash: adjust package comment