1. ドキュメント
  2. 貢献ガイド

貢献ガイド

Go プロジェクトはすべての貢献者を歓迎します。

このドキュメントは、Go プロジェクトに貢献するプロセスを支援するためのガイドです。Go プロジェクトの貢献プロセスは、他のオープンソースプロジェクトで使用されているプロセスとは少し異なります。Git と Go の基本的な理解があることを前提としています。

ここでの情報に加えて、Go コミュニティは コードレビュー Wiki ページを管理しています。レビュープロセスを学ぶにつれて、Wiki に自由に貢献してください。

gccgo フロントエンドは別の場所にあります。 gccgo への貢献 を参照してください。

貢献者になる

概要

最初のステップは、Go 貢献者として登録し、環境を構成することです。次に、必要な手順のチェックリストを示します。

必要に応じて、これらの手順を順を追って説明する自動化ツールがあります。実行するだけです

$ go install golang.org/x/tools/cmd/go-contrib-init@latest
$ cd /code/to/edit
$ go-contrib-init

この章の残りの部分では、これらの手順について詳しく説明します。上記の手順を手動またはツールを使用して完了した場合は、コードを貢献する前に に進んでください。

ステップ 0: Google アカウントを選択する

Go への貢献は、特定のメールアドレスを持つ Google アカウントを通じて行われます。プロセス全体および後続のすべての貢献で同じアカウントを使用するようにしてください。個人アドレスを使用するか、企業アドレスを使用するかを決定する必要がある場合があります。この選択は、作成して送信するコードの著作権を誰が所有するかによって異なります。使用するアカウントを決定する前に、雇用主とこのトピックについて話し合うことをお勧めします。

Google アカウントは、Gmail メールアカウント、G Suite 組織アカウント、または外部メールアドレスに関連付けられたアカウントのいずれかになります。たとえば、G Suite で管理されていない既存の企業メールを使用する必要がある場合は、既存のメールアドレスに関連付けられた アカウントを作成できます。

また、Git ツールが選択したメールアドレスを使用してコミットを作成するように構成されていることを確認する必要があります。Git をグローバルに（すべてのプロジェクトのデフォルトとして）構成するか、ローカルに（単一の特定のプロジェクトに対して）構成できます。次のコマンドで現在の構成を確認できます

$ git config --global user.email  # check current global config
$ git config user.email           # check current local config

構成済みアドレスを変更するには

$ git config --global user.email name@example.com   # change global config
$ git config user.email name@example.com            # change local config

ステップ 1: 貢献者ライセンス契約

Go プロジェクトに最初の変更を送信する前に、次の 2 つの CLA のいずれかを完了している必要があります。署名する必要がある CLA は、作品の著作権を誰が所有しているかによって異なります。

現在署名されている契約を確認し、Google Developers 貢献者ライセンス契約 Web サイトで新しい契約に署名できます。貢献の著作権者が別の Google オープンソースプロジェクトに関連してすでに契約を完了している場合は、再度完了する必要はありません。

送信するコードの著作権者が変更された場合（たとえば、新しい会社に代わってコードの貢献を開始する場合）、golang-dev メーリングリストにメールを送信してください。これにより、状況が通知されるため、適切な契約が完了していることを確認できます。

ステップ 2: git 認証を構成する

メインの Go リポジトリは、Google がホストする Git サーバーである go.googlesource.com にあります。Web サーバーでの認証は Google アカウントを通じて行われますが、コンピューターで git を構成してアクセスする必要もあります。次の手順に従います

  1. go.googlesource.com にアクセスし、ページの右上のメニューバーにある「パスワードを生成」をクリックします。サインインするために accounts.google.com にリダイレクトされます。
  2. サインインすると、「Git を構成する」というタイトルのページが表示されます。このページには、ローカルで実行すると、固有の認証キーを保持するように Git を構成するパーソナライズされたスクリプトが含まれています。このキーは、SSH キーの動作と同様に、サーバーで生成および格納されるキーとペアになっています。
  3. このスクリプトをターミナルでローカルにコピーして実行し、秘密の認証トークンを .gitcookies ファイルに保存します。Windows コンピューターを使用していて cmd を実行している場合は、代わりに黄色のボックスの手順に従ってコマンドを実行する必要があります。それ以外の場合は、通常のスクリプトを実行します。

ステップ 3: Gerrit アカウントを作成する

Gerrit は、Go メンテナーがコードの提出について話し合い、レビューするために使用するオープンソースツールです。

アカウントを登録するには、 go-review.googlesource.com/login/ にアクセスし、上記で使用したのと同じ Google アカウントを使用して一度サインインします。

ステップ 4: git-codereview コマンドをインストールする

Go への変更は、誰が変更を加えたかに関係なく、受け入れられる前にレビューする必要があります。git-codereview と呼ばれるカスタム git コマンドは、Gerrit に変更を送信するのを簡素化します。

を実行して、git-codereview コマンドをインストールします。

$ go install golang.org/x/review/git-codereview@latest

git コマンドが git-codereview を見つけられるように、シェルパスにインストールされていることを確認してください。チェックしてください

$ git codereview help

はヘルプテキストを出力し、エラーは出力しません。エラーが出力された場合は、$GOPATH/bin が $PATH に含まれていることを確認してください。

Windows では、git-bash を使用している場合、git-codereview.exe が git exec-path にあることを確認する必要があります。 git --exec-path を実行して正しい場所を見つけ、シンボリックリンクを作成するか、$GOPATH/bin からこのディレクトリに実行可能ファイルをコピーします。

コードを貢献する前に

プロジェクトはコードパッチを歓迎しますが、すべてがうまく調整されていることを確認するために、作業を開始する前に重要な変更について話し合う必要があります。新しい issue を提出するか、既存の issue を主張することにより、issue トラッカーで貢献する意向を表明することをお勧めします。

貢献する場所

Go プロジェクトは、Go 言語のソースコードを含むメインの go リポジトリと、多くの golang.org/x/... リポジトリで構成されています。これらには、Go をサポートするさまざまなツールとインフラストラクチャが含まれています。たとえば、golang.org/x/pkgsite は pkg.go.dev 用、golang.org/x/playground は Go プレイグラウンド用、golang.org/x/tools には Go 言語サーバー gopls を含むさまざまな Go ツールが含まれています。すべての golang.org/x/... リポジトリのリストは、go.googlesource.com で確認できます。

issue トラッカーを確認する

どのような貢献をするかを知っている場合でも、アイデアを探している場合でも、issue トラッカー は常に最初に行くべき場所です。issue は、分類してワークフローを管理するためにトリアージされます。

golang.org/x/... リポジトリの大部分もメインの Go issue トラッカーを使用しています。ただし、これらのリポジトリの一部は個別に issue を管理しているため、貢献したいリポジトリの正しいトラッカーを確認してください。

ほとんどの issue には、次のワークフローラベルのいずれかがマークされます。

GitHub の検索機能を使用して、支援する issue を見つけることができます。例：

新しい問題について issue を開く

非常に些細な変更を除いて、すべての貢献は既存の issue に関連付けられている必要があります。自由に issue を開き、計画について話し合ってください。このプロセスにより、全員が設計を検証する機会が得られ、作業の重複を防ぎ、アイデアが言語とツールの目標に合致することを保証します。また、コードが記述される前に設計が健全であることを確認します。コードレビューツールは、高レベルの議論の場ではありません。

作業を計画する際には、GoプロジェクトはメインのGoリポジトリに対して6ヶ月間の開発サイクルに従っていることに注意してください。各サイクルの後半は3ヶ月間の機能凍結期間であり、この期間中はバグ修正とドキュメントの更新のみが受け入れられます。機能凍結期間中に新しいコントリビューションを送信することはできますが、凍結が解除されるまでマージされません。凍結は、メインリポジトリ全体と、リリースに含まれるバイナリをビルドするために必要なgolang.org/x/...リポジトリのコードに適用されます。標準ライブラリとgoコマンドにベンダリングされているパッケージのリストを参照してください。

言語、ライブラリ、またはツールへの重要な変更（メインリポジトリとすべてのgolang.org/xリポジトリのAPIの変更、およびgoコマンドのコマンドラインの変更を含む）は、受け入れられる前に変更提案プロセスを経る必要があります。

機密性の高いセキュリティ関連の問題（のみ！）は、security@golang.orgに報告してください。

GitHub経由での変更の送信

GitHubフローに既に精通している初めてのコントリビューターは、Goのコントリビューションにも同じプロセスを使用することをお勧めします。GoのメンテナーはコードレビューにGerritを使用していますが、GitHubのプルリクエストをGerritに同期させるために、Gopherbotというボットが作成されています。

通常どおりGitHubのプルリクエストを開きます。Gopherbotは対応するGerrit変更リスト（「CL」）を作成し、GitHubのプルリクエストにそのリンクを投稿します。プルリクエストの更新はGerrit CLにも反映されます。誰かがCLにコメントすると、そのコメントはプルリクエストにも投稿されるため、通知を受け取ります。

留意すべき事項

Gerrit経由での変更の送信

少なくとも現時点では、GerritとGitHubを完全に同期させることはできません。そのため、Gerritを学ぶことをお勧めします。Gerritは異なりますが強力であり、Gerritに精通することでフローを理解するのに役立ちます。

概要

これは、プロセス全体の概要です。

このセクションの残りの部分では、これらの手順について詳しく説明します。

ステップ1：ソースコードのクローン

最近のGoのインストールに加えて、正しいリポジトリからチェックアウトされたソースのローカルコピーが必要です。Goソースリポジトリは、GOPATH（デフォルトではホームディレクトリのgoディレクトリ）の外側であれば、ローカルファイルシステムの任意の場所にチェックアウトできます。go.googlesource.com（GitHubではありません）からクローンを作成します。

メインのGoリポジトリ

$ git clone https://go.googlesource.com/go
$ cd go

golang.org/x/...リポジトリ

（この例ではgolang.org/x/tools）
$ git clone https://go.googlesource.com/tools
$ cd tools

ステップ2：新しいブランチで変更を準備する

各Goの変更は、masterブランチから作成された個別のブランチで行う必要があります。通常のgitコマンドを使用して、ブランチを作成し、ステージングエリアに変更を追加できます。

$ git checkout -b mybranch
$ [edit files...]
$ git add [files...]

変更をコミットするには、git commitの代わりにgit codereview changeを使用します。

$ git codereview change
(open $EDITOR)

通常どおり、お気に入りのエディターでコミットの説明を編集できます。git codereview changeコマンドは、下部に一意のChange-Id行を自動的に追加します。この行は、Gerritが同じ変更の連続アップロードを照合するために使用されます。編集または削除しないでください。Change-Idは次のようになります。

Change-Id: I2fbdbffb3aab626c4b6f56348861b7909e3e8990

このツールは、ソースコードに対してgo fmtを実行したかどうか、およびコミットメッセージが推奨される形式に従っているかどうかもチェックします。

ファイルを再度編集する必要がある場合は、新しい変更をステージングし、git codereview changeを再実行できます。後続の実行ごとに、Change-Idを保持しながら既存のコミットが修正されます。

各ブランチに常に単一のコミットを保持するようにしてください。誤ってコミットを追加した場合は、git rebaseを使用してそれらを1つにまとめることができます。

ステップ3：変更をテストする

コードを記述してテストしましたが、コードをレビューのために送信する前に、_ツリー全体のすべてのテスト_を実行して、変更によって他のパッケージやプログラムが壊れていないことを確認してください。

メインのGoリポジトリの場合

これは、all.bashを実行することで実行できます。

$ cd go/src
$ ./all.bash

（Windowsでビルドするには、all.batを使用します）

しばらく実行して多くのテスト出力を出力した後、コマンドは次を出力して終了するはずです。

ALL TESTS PASSED

all.bashの代わりにmake.bashを使用して、テストスイートを実行せずにコンパイラと標準ライブラリをビルドすることもできます。goツールがビルドされると、Goリポジトリをクローンしたディレクトリの下のbin/goとしてインストールされ、そこから直接実行できます。変更をすばやくテストする方法に関するセクションも参照してください。

golang.org/x/...リポジトリの場合

リポジトリ全体のテストを実行します（この例ではgolang.org/x/tools）

$ cd tools
$ go test ./...

ビルドステータスが気になる場合は、ビルドダッシュボードを確認できます。テストの失敗は、コードレビューのTryBotによっても検出される場合があります。

golang.org/x/vscode-goなど、一部のリポジトリには異なるテストインフラストラクチャがあるため、常に作業しているリポジトリのドキュメントを確認してください。リポジトリのルートにあるREADMEファイルには、通常、この情報が含まれています。

ステップ4：レビューのために変更を送信する

変更の準備が整い、ツリー全体でテストされたら、レビューのために送信します。これは、名前にもかかわらず、何も直接メールで送信しないmailサブコマンドを使用して行われます。Gerritに変更を送信するだけです。

$ git codereview mail

Gerritは変更に番号とURLを割り当てます。これは、git codereview mailによって次のように出力されます。

remote: New Changes:
remote:   https://go-review.googlesource.com/99999 math: improved Sin, Cos and Tan precision for very large arguments

代わりにエラーが発生した場合は、メールエラーのトラブルシューティングセクションを確認してください。

変更がオープンなGitHub issueに関連していて、推奨されるコミットメッセージ形式に従っている場合、issueはボットによって数分以内に更新され、コメントにGerritの変更へのリンクが追加されます。

ステップ5：レビュー後に変更を修正する

GoのメンテナーはGerritでコードをレビューし、電子メールで通知が届きます。Gerritでレビューを確認し、そこでコメントできます。必要に応じて、電子メールを使用して返信することもできます。

レビュー後に変更を修正する必要がある場合は、以前に作成したのと同じブランチでファイルを編集し、Gitステージングエリアに追加してから、git codereview changeでコミットを修正します。

$ git codereview change     # amend current commit
(open $EDITOR)
$ git codereview mail       # send new changes to Gerrit

コミットの説明を変更する必要がない場合は、エディターを保存して終了するだけです。特別なChange-Id行には触れないでください。

繰り返しますが、各ブランチに常に単一のコミットを保持するようにしてください。誤ってコミットを追加した場合は、git rebaseを使用してそれらを1つにまとめることができます。

適切なコミットメッセージ

Goのコミットメッセージは、このセクションで説明する特定の規則のセットに従います。

適切なコミットメッセージの例を次に示します。

math: improve Sin, Cos and Tan precision for very large arguments

The existing implementation has poor numerical properties for
large arguments, so use the McGillicutty algorithm to improve
accuracy above 1e10.

The algorithm is described at https://wikipedia.org/wiki/McGillicutty_Algorithm

Fixes #159

最初の行

変更の説明の最初の行は、慣例的に、変更の短い1行の要約であり、最初に影響を受けるパッケージがプレフィックスとして付けられます。

経験則として、「この変更はGoを_____に変更します」という文を完成させるように記述する必要があります。つまり、大文字で始まらず、完全な文ではなく、変更の結果を実際に要約しています。

最初の行の後に空行を追加します。

主な内容

説明の残りの部分は詳細を説明し、変更のコンテキストを提供し、変更の内容を説明する必要があります。Goのコメントと同様に、正しい句読点を使用して完全な文で記述します。HTML、Markdown、またはその他のマークアップ言語は使用しないでください。

変更がパフォーマンスに影響を与える場合は、ベンチマークデータなどの関連情報を追加します。benchstatツールは、慣例的に、変更の説明のためにベンチマークデータのフォーマットに使用されます。

issueの参照

特別な表記「Fixes #12345」は、変更をGo issueトラッカーのissue 12345に関連付けます。この変更が最終的に適用されると、issueトラッカーはissueを自動的に修正済みとしてマークします。

変更がissueの解決に向けた部分的な手順である場合は、代わりに「Updates #12345」と記述します。これにより、issueにGerritの変更へのリンクがコメントとして残されますが、変更が適用されてもissueはクローズされません。

golang.org/x/...リポジトリに対して変更を送信する場合は、変更がx /リポジトリではなくメインリポジトリのissueにリンクされていることを確認するために、GitHubでサポートされている完全修飾構文を使用する必要があります。ほとんどのissueは、メインリポジトリのissueトラッカーで追跡されます。正しい形式は「Fixes golang/go#159」です。

レビュープロセス

このセクションでは、レビュープロセスと、変更がメールで送信された後にレビューにどのように取り組むかについて詳しく説明します。

初心者にありがちな間違い

変更がGerritに送信されると、通常は数日以内にトリアージされます。メンテナーは変更を確認し、初期レビューを提供します。初めての貢献者の場合、このレビューは通常、基本的な体裁と一般的な間違いに焦点を当てています。これらには、次のようなものが含まれます。

トライボット

変更の最初の確認後、メンテナーはトライボットをトリガーします。トライボットは、いくつかの異なるアーキテクチャで完全なテストスイートを実行するサーバーのクラスターです。ほとんどのトライボットは数分で完了し、結果を確認できるリンクがGerritに投稿されます。

トライボットの実行が失敗した場合は、リンクをたどり、テストが失敗したプラットフォームの完全なログを確認してください。何が問題だったのかを理解し、パッチを更新して修正し、再度アップロードしてください。メンテナーは、問題が修正されたかどうかを確認するために、新しいトライボットの実行をトリガーします。

ツリーが一部のプラットフォームで数時間壊れている場合があります。トライボットによって報告された障害がパッチに関連していないと思われる場合は、ビルドダッシュボードにアクセスし、同じプラットフォームの他の最近のコミットに同じ障害が表示されているかどうかを確認してください。この場合、障害が変更に関連していないことをGerritにコメントして、メンテナーが状況を理解するのに役立ててください。

レビュー

Goコミュニティは非常に徹底的なレビューを重視しています。各レビューコメントをチケットのように考えてください。提案を実装するか、レビュアーを納得させることで、何らかの方法で「クローズ」することが期待されます。

変更を更新した後、レビューコメントを確認し、すべてに返信してください。レビュアーの提案を実装したことを示すために「完了」ボタンをクリックして返信できます。そうでない場合は、「返信」をクリックして、実装しなかった理由、または代わりに何をしたかを説明してください。

変更が複数回のレビューを経て、1人以上のレビュアーが毎回新しいコメントを作成し、更新された変更を待ってから再度レビューするのは perfectly normal です。このサイクルは経験豊富な貢献者でも発生するため、落胆しないでください。

投票規則

決定に近づくにつれて、レビュアーは変更にコードレビューの「投票」を適用します。2つの可能な投票があります。

送信するには、変更にはメンテナーからのコードレビュー+2が必要です。

メンテナーは、変更に保留+1の投票を適用して、現在送信すべきでない変更をマークすることもできます（たとえば、変更の新しいAPIの提案レビューが完了していないため）。

送信するには、変更にメンテナーからの保留+1投票があってはなりません。

最後に、送信するには、変更には、変更のアップローダーまたは少なくともコードレビュー+1を投票するレビュアーとして、2人のGoogle従業員の関与が必要です。この要件は、コンプライアンスとサプライチェーンセキュリティの理由によるものです。

承認された変更の送信

変更の準備が整うと、メンテナーは変更を送信し、Gerritリポジトリにコミットとして追加します。

場合によっては、メンテナーは変更を承認してもすぐに送信したくない場合があるため（たとえば、ツリーが一時的にフリーズしている場合など）、（承認と送信の）2つの手順は分かれています。

変更を送信すると、リポジトリにチェックインされます。変更の説明には、コードレビューへのリンクが含まれ、リポジトリの変更へのリンクで更新されます。変更を統合するために使用されるメソッドはGitの「Cherry Pick」であるため、リポジトリのコミットハッシュは送信操作によって変更されます。

変更が数日間承認されても送信されない場合は、Gerritにコメントを書いて送信をリクエストしてください。

詳細情報

ここでの情報に加えて、Goコミュニティはコードレビューwikiページを管理しています。レビュープロセスについて詳しく知ったら、このページに貢献してください。

その他のトピック

このセクションでは、問題/編集/コードレビュー/送信プロセス自体以外のその他のコメントをまとめています。

Gopls

メインのGoリポジトリで作業し、エディターで `gopls` を使用する場合、`gopls` によって呼び出される `go` コマンドは、作業しているソースコードのバージョンに対応している必要があります。 `go` コマンドは `make.bash` でビルドでき、`bin` ディレクトリを `PATH` に追加する必要があります。詳細は、 Gopls：高度なトピックを参照してください。

Goリポジトリのファイルには、煩雑さを避け、リストを最新の状態に保つ必要がないように、作成者の名前が記載されていません。代わりに、あなたの名前は変更ログに表示されます。

あなたが貢献する新しいファイルは、標準の著作権ヘッダーを使用する必要があります

// Copyright 2024 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

リポジトリ内のファイルは、追加された年の著作権で保護されています。変更するファイルの著作権の年を更新しないでください。

メールエラーのトラブルシューティング

`git` `codereview` `mail` コマンドが失敗する最も一般的な原因は、コミットのメールアドレスが登録プロセスで使用したものと一致しないためです。
次のようなものが表示された場合...

remote: Processing changes: refs: 1, done
remote:
remote: ERROR:  In commit ab13517fa29487dcf8b0d48916c51639426c5ee9
remote: ERROR:  author email address XXXXXXXXXXXXXXXXXXX
remote: ERROR:  does not match your user account.

このリポジトリのGitが登録したメールアドレスを使用するように設定する必要があります。この問題が再発しないようにメールアドレスを変更するには、次を実行します

$ git config user.email email@address.com

次に、このコマンドを使用して、コミットがこの代替メールアドレスを使用するように変更します

$ git commit --amend --author="Author Name <email@address.com>"

次に、次を実行して再試行します

$ git codereview mail

変更の迅速なテスト

コードツリーへの変更ごとに `all.bash` を実行するのは負担です。変更を送信する前に実行することを強くお勧めしますが、通常の開発サイクル中は、開発中のパッケージのみをコンパイルおよびテストすることをお勧めします。

レビュアーの指定/他のCC

変更の送信につながるディスカッションなどで明示的に指示されていない限り、レビュアーを指定しない方がよいでしょう。すべての変更は、golang-codereviews@googlegroups.comメーリングリストに自動的にCCされます。これが初めての変更の場合、スパムを防ぐために、メーリングリストに表示されるまでにモデレーションの遅延が発生する場合があります。

`-r` または `-cc` オプションを使用して、レビュアーを指定したり、関係者にCCを送信したりできます。どちらも、コンマ区切りのメールアドレスのリストを受け入れます

$ git codereview mail -r joe@golang.org -cc mabel@example.com,math-nuts@swtch.com

クライアントの同期

作業中に、他の人がリポジトリに変更を送信した可能性があります。ローカルブランチを更新するには、次を実行します

$ git codereview sync

（内部的には、これは `git` `pull` `-r` を実行します。）

他者によるコードのレビュー

レビュープロセスの一環として、レビュアーは変更を直接提案できます（GitHubワークフローでは、これはプルリクエストにコミットを添付する他の誰かになります）。 Gerritは、別の開発者によって提案された変更をインポートするのに役立つコマンドへのアクセスを提供するため、ローカルでレビュー/テストできます。インポートするCLのGerritページから、「⋮」メニューを開き、「パッチのダウンロード」リンクをクリックします。好みのgitワークフローに応じて、適切なコマンドを選択します。オプションは次のようになります

$ git fetch https://go.googlesource.com/review refs/changes/21/13245/1 && git checkout FETCH_HEAD

元に戻すには、作業していたブランチに戻します。

gitエイリアスの設定

`git-codereview` コマンドは、たとえば次のように入力してシェルから直接実行できます。

$ git codereview sync

ただし、`git-codereview` 自体のサブコマンドのエイリアスを設定する方が便利です。そのため、上記は次のようになります。

$ git sync

git-codereview のサブコマンドは、Git 自身のコマンドと区別されるように選択されているため、これらのエイリアスを定義しても安全です。インストールするには、このテキストを Git 設定ファイル（通常はホームディレクトリの .gitconfig）にコピーします。

[alias]
	change = codereview change
	gofmt = codereview gofmt
	mail = codereview mail
	pending = codereview pending
	submit = codereview submit
	sync = codereview sync

複数の依存関係のある変更を送信する

上級ユーザーは、関連するコミットを単一のブランチにスタックしたい場合があります。Gerrit では、変更が相互に依存して依存関係チェーンを形成できます。各変更は個別に承認および送信する必要がありますが、依存関係はレビュー担当者に表示されます。

依存関係のある変更のグループを送信するには、各変更を同じブランチの異なるコミットとして保持し、次に以下を実行します。

$ git codereview mail HEAD

単一の変更を送信する際には通常必要ありませんが、HEAD を明示的に指定してください。詳細は、git-codereview ドキュメントをご覧ください。

go.dev は、Google の Cookie を使用してサービスの提供と品質の向上、トラフィックの分析を行っています。詳細