cybercyst/go
1
0
Fork 0
mirror of https://github.com/golang/go.git synced 2025-05-05 15:43:04 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Updated Deprecated (markdown)

Russ Cox 2022-11-22 10:19:39 -05:00
parent bb0a09a138
commit 372309661d
1 changed files with 20 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
Deprecated.md

@ -1,24 +1,35 @@
Sometimes a struct field, function, type, or even a whole package becomes
redundant or unnecessary, but must be kept for compatibility with existing
programs.
Sometimes an API feature such as a struct field, function, type, or even a whole package becomes
redundant or unnecessary.
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.
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
deprecation, and a recommendation on what to use instead, if applicable.
The paragraph does not have to be the last paragraph in the doc comment.
[Some tools will warn on use of deprecated identifiers](https://staticcheck.io/docs/checks#SA1019)
and their docs [are hidden on pkg.go.dev now that #40850 is implemented](https://go.dev/issue/40850).
and their docs [are hidden on pkg.go.dev](https://go.dev/issue/40850).
The original issue to document the "Deprecated" convention was [issue #10909](https://go.dev/issue/10909).
Note that, if function `F1` is being replaced by function `F2`,
If function `F1` is being replaced by function `F2`
and the first release in which `F2` is available is Go 1.N,
then we can add an official deprecation notice in release Go 1.N+2.
then an official deprecation notice for `F1` should not be
added until Go 1.N+2.
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.
An API feature should only be marked deprecated if its
use is problematic in some way, not simply because something
newer exists.
## Examples
```