Bump the sdk go version to 1.20, document when go versions should be …

…updated (hashicorp#20278)

api/go.mod

@@ -1,9 +1,12 @@
 module github.com/hashicorp/vault/api
 
+// The Go version directive for the api package should normally only be updated when
+// code in the api package requires a newer Go version to build.  It should not
+// automatically track the Go version used to build Vault itself.  Many projects import
+// the api module and we don't want to impose a newer version on them any more than we
+// have to.
 go 1.19
 
-replace github.com/hashicorp/vault/sdk => ../sdk
-
 require (
 	github.com/cenkalti/backoff/v3 v3.0.0
 	github.com/go-test/deep v1.0.2

go.mod

@@ -1,6 +1,16 @@
 module github.com/hashicorp/vault
 
-go 1.19
+// The go version directive value isn't consulted when building our production binaries, 
+// and the vault module isn't intended to be imported into other projects.  As such the
+// impact of this setting is usually rather limited.  Note however that in some cases the
+// Go project introduces new semantics for handling of go.mod depending on the value.
+//
+// The general policy for updating it is: when the Go major version used on the branch is 
+// updated. If we choose not to do so at some point (e.g. because we don't want some new
+// semantic related to Go module handling), this comment should be updated to explain that.
+//
+// Whenever this value gets updated, sdk/go.mod should be updated to the same value.
+go 1.20
 
 replace github.com/hashicorp/vault/api => ./api
 

sdk/go.mod

@@ -1,6 +1,8 @@
 module github.com/hashicorp/vault/sdk
 
-go 1.19
+// The Go version directive for the sdk package should be updated whenever the
+// the root go.mod for the hashicorp/vault project gets updated.
+go 1.20
 
 require (
 	github.com/armon/go-metrics v0.3.9