math/rand: Add auto-seed info to deprecation notice #59331
Description
The current deprecation notice on rand.Seed only addresses what I think is a tiny corner case for why most applications call rand.Seed.
Deprecated: Programs that call Seed and then expect a specific sequence of results from the global random source (using functions such as Int) can be broken when a dependency changes how much it consumes from the global random source. To avoid such breakages, programs that need a specific result sequence should use NewRand(NewSource(seed)) to obtain a random generator that other packages cannot access.
The thing is, since the beginning of time, many applications have been calling rand.Seed on startup because otherwise math/rand got seeded with a static value. So they actually wanted the opposite of what this deprecation notice says. Which makes this deprecation notice very confusing.
I know that there is a sentence above the notice in the docs that states that the seed is now set randomly at program startup, but many automated tools simply extract the deprecation notice to display to the developer, and the existing notice only applies to what I expect is about 0.1% of usage, and says nothing about the 99.9% case, where a dev was doing the (previously, mostly) right thing, and calling something like rand.Seed(time.Now().UnixNano()).
One more short sentence at the beginning of the deprecation notice would save a lot of confusion. Something like this:
Deprecated: The generator is now seeded randomly at program startup. Programs that call Seed and then expect a specific sequence of results from the global random source (using functions such as Int) can be broken when a dependency changes how much it consumes from the global random source. To avoid such breakages, programs that need a specific result sequence should use NewRand(NewSource(seed)) to obtain a random generator that other packages cannot access.
Personally, I think the existing deprecation notice is too long and editorializes too much about what could go wrong. I'd skip right to the important bits:
Deprecated: The generator is now always seeded randomly at program startup. Programs that need a specific sequence of results should use New(NewSource(seed)) to obtain a random generator.
(also note that the current documentation has a typo in the deprecation notice where it says NewRand( but should say New()
What version of Go are you using (go version)?
1.20
Does this issue reproduce with the latest release?
yes