Go Wiki: Deprecated

structフィールド、関数、型、あるいはパッケージ全体といったAPI機能が、冗長になったり不要になったりする場合があります。新しいプログラムでの使用を推奨しない場合、その機能に「非推奨 (deprecated)」のマークを付けます。

他のシステムとは対照的に、API機能が非推奨になったからといって、将来的に削除されるわけではありません。むしろ、Go 1互換性の原則により、既存のプログラムが引き続き動作するように、その機能は非推奨の形式で保持されます。

識別子が使用されるべきではないことを示すには、そのドキュメントコメントにDeprecated:で始まる段落を追加し、非推奨に関する情報と、もしあれば代わりに何を使用すべきかについての推奨事項を続けます。この段落は、ドキュメントコメントの最後の段落である必要はありません。

一部のツールは非推奨の識別子の使用について警告を発します。また、そのドキュメントはpkg.go.devで非表示にされます。

関数F1が関数F2に置き換えられ、F2が利用可能になる最初のリリースがGo 1.Nである場合、F1の公式な非推奨通知はGo 1.N+1まで追加すべきではありません。これにより、Go開発者は、サポートされているすべてのGoバージョンにF2が含まれており、簡単に切り替えることができる場合にのみF1が非推奨であると認識できます。

API機能を非推奨にすることは、その機能を使用している何百万ものGo開発者にとって作業と決定を必要とします。API機能を非推奨にすることはAPIの変更であり、提案プロセスを使用して議論されなければなりません。

例

type ResponseRecorder struct {
    // HeaderMap contains the headers explicitly set by the Handler.
    // It is an internal detail.
    //
    // Deprecated: HeaderMap exists for historical compatibility
    // and should not be used. To access the headers returned by a handler,
    // use the Response.Header map as returned by the Result method.
    HeaderMap http.Header

// Package rc4 implements the RC4 stream cipher.
//
// Deprecated: RC4 is cryptographically broken and should not be used
// except for compatibility with legacy systems.
//
// This package is frozen and no new functionality will be added.
package rc4

標準ライブラリには他にもいくつかの例があります。