Deprecated: reorganize and mention modernizers Change-Id: I85768f103a592c6ad29b1cce4aa8ee833702a371 Reviewed-on: https://go-review.googlesource.com/c/wiki/+/744701 Reviewed-by: Carlos Amedee <carlos@golang.org>
diff --git a/Deprecated.md b/Deprecated.md index 3306fa9..26c587c 100644 --- a/Deprecated.md +++ b/Deprecated.md
@@ -7,11 +7,13 @@ When we want to discourage new programs from using it, we mark that feature "deprecated". -In contrast to some other systems, an API feature being deprecated -_does not_ mean it is going to be removed in the future. -On the contrary, [Go 1 compatibility](https://go.dev/doc/go1compat) -means the feature will be preserved in its deprecated form -to keep existing programs running. +In general, if an API still works and does not have significant downsides, +we do not formally mark it as deprecated, and instead +simply update the documention to point to the preferred API. +When there is simply a newer, preferred API available, consider +adding a `//go:fix inline` annotation to gently steer consumers +toward the new API. +For changes in the Go standard library, consider proposing a modernizer. To signal that an identifier should not be used, add a paragraph to its doc comment that begins with `Deprecated:` followed by some information about the @@ -21,6 +23,19 @@ [Some tools will warn on use of deprecated identifiers](https://staticcheck.io/docs/checks#SA1019) and their docs [are hidden on pkg.go.dev](https://go.dev/issue/40850). +## Deprecations in the Go standard library + +Marking an API feature deprecated can create work and +decisions for millions of Go developers using the feature. +Deprecating an API feature is an API change that must +be discussed using [the proposal process](https://go.dev/s/proposal). + +In contrast to some other systems, an API feature being deprecated +_does not_ mean it is going to be removed in the future. +On the contrary, [Go 1 compatibility](https://go.dev/doc/go1compat) +means the feature will be preserved in its deprecated form +to keep existing programs running. + If function `F1` is being replaced by function `F2` and the first release in which `F2` is available is Go 1.N, then an official deprecation notice for `F1` should not be @@ -28,11 +43,6 @@ This ensures that Go developers only see `F1` as deprecated when all supported Go versions include `F2` and they can easily switch. -Marking an API feature deprecated can create work and -decisions for millions of Go developers using the feature. -Deprecating an API feature is an API change that must -be discussed using [the proposal process](https://go.dev/s/proposal). - ## Examples ```Go