x/tools: make API changes visible during code review

[adonovan]

API-affecting changes to GOROOT require the api/*.txt files to be altered to reflect the changes. x/tools could benefit from something similar to prevent accidental addition, alteration, or removal of public declarations, and to make API changes easier to review.

cc: @jba, @dmitshur

[gabyhelp]

Related Issues

• proposal: cmd/api: a mechanical approach to compatibility issues #13891 (closed)
• api: API check test should disallow API additions after an api/go1.N.txt is created (currently it does this only after a VERSION file is added) #43956 (closed)
• x/tools/gopls: auto-generate API diff for releases #46652 (closed)
• cmd/release: must run api checker #11943 (closed)
• cmd/api: allow use with external packages #4993 (closed)
• proposal: how to specify mechanical code updates after API changes? #18983 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[mateusz834]

It would be also nice to have this in x/net. I was thinking about this yesterday during a code review.

[dmitshur]

The scope of the proposal process includes "API changes in the main repo and all* golang.org/x repos" (almost all, there are some x/ repos that are not in scope), so it makes sense to cover x/net and others, especially ones whose modules have already reached v1.

It's likely that the way this can be done for x/tools should naturally apply to other x/ repos too.

[kwjw]

Just calling out that the api/*.txt format in GOROOT needs meaningful refactoring to be more thoroughly correct (#56773). If golang.org/x repos want to use a system like this, it could be worth investigating a different design.