Refer looks good. I think we should work these examples over a bit. I'm looking at each of them and have lots of questions. I think this loss of context is what made deprecations error-prone in the first place, so the examples we give should be really good in that they let someone who was not a primary author on the code come in two years later and reason out (with some effort) why the removal is indeed possible at the specified minSupportedVersion.

Reviewed 4 of 4 files at r1, all commit messages.
Reviewable status: complete! 0 of 0 LGTMs obtained (waiting on @celiala and @dt)

pkg/cli/clisqlclient/refer.go line 15 at r1 (raw file):

import "github.com/cockroachdb/cockroach/pkg/clusterversion"

func init() {

What's up with this? Why is there a new package?

pkg/clusterversion/refer.go line 15 at r1 (raw file):

// Refer allows tying one or more objects (or even a code comment, etc)
// to a cluster version, to denote that these objects that be cleaned-up

grammar is off here (probably my bad ;-) )

pkg/clusterversion/refer.go line 38 at r1 (raw file):

// (1) In your code you have:
//
//    // We need to keep it for 22.1, but can remove it once we're on 22.2+ binaries

I would make it a point to avoid referring in code comments to a release in which the "thing" can be removed. This isn't exactly known when the comment is written! See right now, where we are considering bumping the minSuppVersion more slowly. Instead, if we're adding a comment, it should be "can be removed once MinSupportedVersion is >= X".

pkg/clusterversion/refer.go line 50 at r1 (raw file):

//
func Refer(version Key, obj ...interface{}) {
	_ = 0 // no-op

Probably don't need this line.

pkg/jobs/jobspb/refer.go line 20 at r1 (raw file):

	// requests over the table span.
	//
	// TODO(ajwerner): Remove this in 23.1.

"Remove this once MinSupportedVersion > V22_2"

Ideally there would also be a bit more context here. I looked into this, and isn't the association here unnecessarily pessimistic? v22.2 will still use this enum, but only before the cluster version bump. Fully migrated v22.2 (i.e. at V22_2) might also still use this, because we can still turn off MVCC rangedels¹, so we can't really yet say when we can remove this. (If we didn't have the opt-out, we could remove it when the minsupportedversion hits 22.2).

In short, I'm not sure this one is a good example, maybe we can find something that is more easily the right thing?

pkg/jobs/jobspb/refer.go line 26 at r1 (raw file):

	//
	// TODO(ajwerner): Remove this in 23.1.
	clusterversion.Refer(clusterversion.V22_2, SchemaChangeGCProgress_CLEARING)

Ditto

pkg/keys/refer.go line 19 at r1 (raw file):

	// descriptorless.
	// TODO(richardjcai): This should be fully removed in 22.2.
	clusterversion.Refer(clusterversion.V22_1, PublicSchemaID)

Here too re: this being correct - the cluster version that was associated to this was 21.2.18¹ which is already out of scope. I assume there is some follow-up history that means we can only remove this later, but just referring to a cluster version without any explanation is too opaque. The person removing this may not be the author. The author may have made a mistake. There still needs to be enough information here to be able to confirm that everything checks out.