internal/godebugs: test for use of IncNonDefault

A few recent godebugs are missing IncNonDefault uses.
Test for that, so that people remember to do it.
Filed bugs for the missing ones.

For #66215.
For #66216.
For #66217.

Change-Id: Ia3fd10fd108e1b003bb30a8bc2f83995c768fab6
Reviewed-on: https://go-review.googlesource.com/c/go/+/570275
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Damien Neil <dneil@google.com>

1 files changed, 22 insertions, 2 deletions

diff --git a/src/internal/godebug/godebug.go b/src/internal/godebug/godebug.go
index 36bfeaccc4..0756d313e6 100644
--- a/src/internal/godebug/godebug.go
+++ b/src/internal/godebug/godebug.go
@@ -22,8 +22,23 @@
 //	}
 //
 // Each time a non-default setting causes a change in program behavior,
-// code should call [Setting.IncNonDefault] to increment a counter that can
-// be reported by [runtime/metrics.Read].
+// code must call [Setting.IncNonDefault] to increment a counter that can
+// be reported by [runtime/metrics.Read]. The call must only happen when
+// the program executes a non-default behavior, not just when the setting
+// is set to a non-default value. This is occasionally (but very rarely)
+// infeasible, in which case the internal/godebugs table entry must set
+// Opaque: true, and the documentation in doc/godebug.md should
+// mention that metrics are unavailable.
+//
+// Conventionally, the global variable representing a godebug is named
+// for the godebug itself, with no case changes:
+//
+//	var gotypesalias = godebug.New("gotypesalias") // this
+//	var goTypesAlias = godebug.New("gotypesalias") // NOT THIS
+//
+// The test in internal/godebugs that checks for use of IncNonDefault
+// requires the use of this convention.
+//
 // Note that counters used with IncNonDefault must be added to
 // various tables in other packages. See the [Setting.IncNonDefault]
 // documentation for details.
@@ -70,6 +85,11 @@ type value struct {
 // To disable that panic for access to an undocumented setting,
 // prefix the name with a #, as in godebug.New("#gofsystrace").
 // The # is a signal to New but not part of the key used in $GODEBUG.
+//
+// Note that almost all settings should arrange to call [IncNonDefault] precisely
+// when program behavior is changing from the default due to the setting
+// (not just when the setting is different, but when program behavior changes).
+// See the [internal/godebug] package comment for more.
 func New(name string) *Setting {
 	return &Setting{name: name}
 }