cmd/api: api checker should check types for change in comparability

[griesemer]

The api checker checks that we don't change our APIs in a backward-incompatible way.

Generics introduced the constraint comparable which denotes the set of all types which are strictly comparable. An API may define an exported type T which may be strictly comparable (see #56548 for terminology) and such a type T may successfully be used as type argument for comparable type parameters elsewhere.

It's possible to change T without visible API change so that it's not strictly comparable anymore. For instance, given

// T is strictly comparable
type T struct {
   /* exported and unexported fields which are all strictly comparable */
}

one can add a new, unexported field that is not strictly comparable

// T is not strictly comparable anymore
type T struct {
   /* exported and unexported fields which are all strictly comparable */
   unexported any // not strictly comparable
}

The visible API has not changed but T is not not strictly comparable anymore. This may prevent it's use elsewhere.

The api checker should treat such changes as API changes.

Marking for 1.20 as it would be a useful check and could be added late in the cycle.

[griesemer]

See this example for a mechanism that library writers can use to assert strict comparability of exported types they care about.

[mknyszek]

In triage, we decided this might still happen for 1.20, but if it doesn't it can be kicked to the 1.21 milestone.

[mknyszek]

Should we kick this to 1.21?

[griesemer]

This will (probably) require a change to the recorded API text format; this is not just a simple bug fix. Leaving open for 1.22 for visibility but can be moved to 1.23. At some point we should actively work on this.