proposal: api: add mechanism for correlating deprecations with Go versions e.g. <version_deprecated>.txt

[odeke-em]

Just coming here from #37650 in which a user was mistakenly using a long deprecated field net/http/httptest.Recorder.HeaderMap instead of net/http/httptest.Recorder.Result()

While we use the // Deprecated: notice as the de facto standard for deprecating fields, it might be very useful for one to know when a field was deprecated.

I propose that just like we have api/<version>.txt whose entries are of the form:
pkg <PKG_NAME>, <IDENTIFIER>
that we add another form also within that same directory <api/version_deprecated>.txt, whose line content formats will be the exact same as those for api/<version>.txt, so no change in parser, but an addition would be that GoDoc can then quickly look up what was deprecated and when and render that along.

This way we can make for more powerful tooling like, for example pkg.go.dev could give a deprecation policy notice between versions and is even more advantageous:

• if an organization follows a deprecation policy e.g. 6 months, or 2 Go-releases deprecation policy, we can then have a column that shows when code was deprecated and when code needs to be changed
• when cutting releases, we can produce a list of deprecated content

Many Go deprecation notices are loosely followed because for the longest time we didn't have modules so years later, users would still using deprecated fields. This suggestion could help in issuing stale code notices and not just when they switch to a module and have to suddenly re-write their code. This can help with more powerful refactoring.

[bcmills]

CC @julieqiu @jba (since this could also be surfaced in pkg.go.dev)

[jba]

I don't think pkg.go.dev would need that file. It could just figure it out while it "ingests" a new go version, from that version's godoc plus the data from the previous version.

[rsc]

This file seems like an index that can be mechanically derived, not something we should require committing and letting drift out of date. pkg.go.dev can handle the main Go repo just fine, and I wouldn't want to impose new restrictions on other module maintainers for things that we can determine automatically.

[kaey]

staticcheck already flags usage of deprecated symbols
https://staticcheck.io/docs/checks#SA1019

[rsc]

Based on the discussion above, this sounds like a likely decline (better to do automatically instead of a separate file that must be kept up to date).

[rsc]

No change in consensus. Declined.

[odeke-em]

Given that there is a way for ingestion to happen, I am fine with the decline. Thank you for the discourse and analyses everyone.

[rsc]

Forgot to close.