公開Goライブラリを、使う人のコードを壊さずに変える

## コードを変える前に、対応するGoのバージョンとブランチを確かめる 正しさ、後方互換性、適用される外部仕様を主要な受け入れ基準として扱う。コードを変更する前に、次を特定する。 - 現在の開発ブランチと最新の安定メンテナンスブランチ - 利用者向けに対応する最小Goバージョン - リポジトリの開発に必要な、より新しいGoバージョンとツールチェーン - 公開され、互換性保証の対象となるAPIを構成するパッケージ - import可能だがセマンティックバージョニングの保証対象外で、実際には利用されている内部または実験的パッケージ 「セマンティックバージョニングの対象外」であることを「壊しても安全」と見なしてはならない。実際の利用者に影響し得る動作変更やAPI変更を明示する。リポジトリの方針に従い、機能追加は開発ブランチへ、修正は適切な安定ブランチへ振り分ける。 公開パッケージでは、宣言された最小Goバージョンより新しい標準ライブラリAPIや言語機能を避ける。未対応機能が利用者へ届く前に失敗するよう、互換性ゲートをビルド内で実行可能な状態に保つ。 ## プロジェクトのツールで、チェックとテストを回す 使い慣れたコマンドで代用せず、プロジェクトのタスクランナーと指定されたフォーマッターを使う。既定の検証ターゲットには、コンパイル、ライセンス確認、フォーマット確認、モジュール確認、lint、短時間テストを含める。 テストは次の2段階で維持する。 - 素早いフィードバック用の、race検出を有効にした短時間スイート - リポジトリが必要とするサービス依存関係と長いタイムアウトを備えた完全な統合スイート 統合テストがサーバー状態を共有する場合、完全なスイートは直列に実行し、所要時間を短くする目的だけで並列度を上げてはならない。サービスの接続先は設定可能にしつつ、文書化されたローカル既定値を維持する。 低レベルの動作がアーキテクチャに依存する場合は、複数アーキテクチャ向けのlintまたはコンパイル確認を行う。特にatomicアクセスを使う場合は32-bitターゲットを検証する。atomicにアクセスする64-bitフィールドは、構造体の先頭に置くか型付きatomicラッパーを使うなど、安全なアラインメントを確保しなければならない。 ## エラーと公開APIは、ライブラリの今の書き方に合わせる リポジトリで確立されたパターンに合わせる。 - `%w`を使って文脈付きでエラーをラップし、メッセージ文字列の照合ではなく`errors.Is`または`errors.As`で比較する - ブロックするすべての公開メソッドで`context.Context`を第1引数にし、競合する実時間タイマーを新設せず、呼び出し元のcontextから期限を導出する - キー順が重要なコマンドやデータには順序付きドキュメント型を使い、順序が無関係な場合だけmap型を使い、低レベルのバイト列ベース表現は正当化できるホットパスに限る - 公開識別子には省略形ではなく完全な単語を使い、識別子を主語にしたdoc commentを付け、新しいオプションではプロジェクトのbuilderまたはsetterパターンに従う 現在のパッケージ配置と移行上の決定を維持する。廃止されたimportパスや旧式の公開抽象を復活させてはならない。 コマンド監視や診断から認証処理が観測できる場合、イベントを見せる前に、認証情報を扱うコマンドをマスキング方針へ追加する。機能固有のネイティブ依存関係とビルドタグは、セットアップ手順とテスト手順に明記し続ける。 ## 単体テストと統合テストを分けて置き、変更に合ったテストを回す 単体テストは実装の隣に置き、統合テストはリポジトリの統合テスト領域に置く。プロジェクトのassertion helperを使い、部分文字列による検証より`ErrorIs`のような意味に基づく検証を優先する。 統合動作には、デプロイ構成、fail pointの注入、イベント取得に対応した標準のトポロジー認識型ハーネスを使う。仕様fixtureは指定されたテストデータ領域に置き、clone後に必要なsubmoduleまたはfixture取得元を初期化する。追跡可能性が重要な場合は、文章形式のテストケース番号を根拠となる仕様の番号に合わせる。 レビュー前に既定の検証ターゲットを実行する。変更が統合動作または共有サーバー状態に触れる場合は、完全なスイートを直列に実行する。限定的な単体テストの合格だけでは、複数アーキテクチャ、互換性、仕様依存の変更に対する十分な証拠にならない。 ## テスト結果と互換性への影響を、pull requestにまとめる コミットメッセージとpull requestタイトルには、指定された作業項目のprefixを使う。pull requestでは、利用者に見える動作、互換性への影響、テストの証拠、ブランチを選んだ理由を説明する。 変更内容に応じた証拠を追加する。 - 公開APIを変更した場合は、リポジトリのAPIレポートを生成してpull requestへ含める - 利用者に影響する破壊的変更では、対応する移行ガイドを更新する - 仕様準拠の変更では、実装が満たす正確な要件を引用する - import可能な実験的パッケージを変更した場合は、セマンティックバージョニング上の義務がなくても、破壊的影響を明示する ローカルでビルドできたことだけを理由に、変更を準備完了としてはならない。準備完了には、リポジトリの既定確認に加え、直接関係する互換性、統合、API、仕様のすべてのゲートを通過する必要がある。