Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

[インデックス 13965] ファイルの概要

このコミットは、Goプロジェクトへの貢献を考えている開発者向けに、ドキュメントの重要な情報を追加・修正するものです。具体的には、Goのソースコードからインストールする方法に関するドキュメントへのリンクを更新し、貢献者がリリースブランチから開発用のデフォルトブランチに切り替えるべきであるという注意喚起を追加しています。

コミット

commit 452f40f8e04dfea421af21378c8579464ac66e5e
Author: Jonathan Feinberg <feinberg@google.com>
Date:   Wed Sep 26 14:39:31 2012 -0400

    doc: add important info for would-be go contributors.
    
    Link to the "installing from source" docs instead of the "installing" docs.
    
    Remind would-be hacker to switch to the default branch from the release branch.
    
    R=rsc
    CC=golang-dev
    https://golang.org/cl/6559043

GitHub上でのコミットページへのリンク

https://github.com/golang/go/commit/452f40f8e04dfea421af21378c8579464ac66e5e

元コミット内容

doc: add important info for would-be go contributors. Link to the "installing from source" docs instead of the "installing" docs. Remind would-be hacker to switch to the default branch from the release branch.

このコミットは、Goプロジェクトへの貢献を考えている人々にとって重要な情報をドキュメントに追加することを目的としています。具体的には、一般的なインストール手順へのリンクを、ソースからのインストール手順へのリンクに修正し、さらに、Goのソースコードを修正して貢献しようとする開発者に対して、リポジトリのブランチをリリースブランチからデフォルト（開発）ブランチに切り替えるよう促す内容が追加されています。

変更の背景

Goプロジェクトはオープンソースであり、多くの開発者がその発展に貢献しています。貢献者がスムーズに開発環境をセットアップし、適切なブランチで作業を開始できるように、ドキュメントの明確性と正確性を向上させる必要がありました。

このコミットが行われた2012年当時、GoプロジェクトはMercurial (Hg) をバージョン管理システムとして使用していました。Mercurialでは、hg clone -u release コマンドでリポジトリをクローンすると、デフォルトで安定版のリリースブランチがチェックアウトされます。しかし、Goのソースコードに貢献する開発者は、最新の開発状況が反映されているデフォルトブランチ（現在のmasterブランチに相当）で作業を行う必要があります。リリースブランチで作業を進めてしまうと、最新の変更とのコンフリクトが発生したり、意図しない動作を引き起こしたりする可能性がありました。

また、Goのインストール方法に関するドキュメントも、一般的なインストール手順とソースからのインストール手順が混同されやすい状況だったと考えられます。貢献者は通常、ソースからGoをビルドして開発環境を構築するため、より直接的に「ソースからのインストール」ドキュメントへ誘導することが求められました。

これらの背景から、貢献者がより効率的かつ正確にGoプロジェクトに貢献できるよう、ドキュメントの改善が図られました。

前提知識の解説

Goプロジェクトへの貢献プロセス

Goプロジェクトへの貢献は、一般的に以下のステップで行われます。

  1. Goのインストール: 開発環境をセットアップします。貢献者は通常、ソースコードからGoをビルドします。
  2. リポジトリのクローン: Goのソースコードリポジトリをローカルにクローンします。
  3. ブランチの切り替え: 開発作業を行うために、適切な開発ブランチ（当時でいうdefaultブランチ）に切り替えます。
  4. コードの変更とテスト: 変更を加え、既存のテストを実行し、必要に応じて新しいテストを作成します。
  5. 変更の提出: Gerritなどのコードレビューシステムを通じて変更を提出し、レビューを受けます。

Mercurial (Hg)

Mercurialは、Gitと同様の分散型バージョン管理システム（DVCS）です。Goプロジェクトは、このコミットが行われた時期にはMercurialを使用していました。Mercurialの基本的なコマンドには以下のようなものがあります。

  • hg clone [URL]: リポジトリをクローンします。
  • hg update [branch_name]: 指定したブランチに作業ディレクトリを切り替えます。
  • hg status: 変更されたファイルの状態を表示します。
  • hg commit: 変更をコミットします。

Mercurialにおける「ブランチ」の概念はGitと似ていますが、実装の詳細には違いがあります。特に、hg clone -u releaseのように-uオプションで特定のブランチを指定してクローンすると、そのブランチがデフォルトでチェックアウトされます。

リリースブランチと開発ブランチ

ソフトウェア開発において、プロジェクトは通常、複数のブランチを管理します。

  • リリースブランチ (Release Branch): 安定版のリリースに対応するコードベースを管理するためのブランチです。通常、バグ修正のみが適用され、新機能の開発は行われません。ユーザーが安定版を使用する際に推奨されるブランチです。
  • 開発ブランチ (Development Branch / Default Branch): 最新の開発状況が反映されるブランチです。新機能の追加、大規模な変更、実験的な機能などがこのブランチで行われます。Goプロジェクトでは、当時defaultブランチがこれに相当し、現在はmasterブランチが同様の役割を担っています。貢献者は、通常この開発ブランチで作業を行います。

貢献者がリリースブランチで作業を開始してしまうと、その後の変更が開発ブランチの最新のコードベースと乖離し、マージが困難になる可能性があります。そのため、貢献者には開発ブランチへの切り替えが推奨されます。

技術的詳細

このコミットは、Goの公式ドキュメントであるHTMLファイルを修正しています。

  1. doc/contribute.html の変更:

    • Goのインストール手順へのリンクが、/doc/install から /doc/install/source へと変更されました。
    • これは、Goプロジェクトに貢献する開発者が、通常はソースコードからGoをビルドして環境を構築するため、より具体的な「ソースからのインストール」ドキュメントへ直接誘導することを意図しています。これにより、貢献者が適切なインストール手順を迅速に見つけられるようになります。

  2. doc/install-source.html の変更:

    • 新しいセクション「(Optional) Switch to the default branch」が追加されました。
    • このセクションでは、Goのソースコードを修正し、プロジェクトに貢献する意図がある場合、リポジトリをリリースブランチからデフォルト（開発）ブランチに切り替える必要があることを説明しています。
    • 具体的なコマンドとして $ hg update default が示されており、Mercurialを使用している開発者に対して、ブランチ切り替えの具体的な手順を提供しています。
    • このステップをスキップした場合の影響（貢献作業が困難になる可能性）も暗に示唆されており、貢献者が適切な開発環境で作業を開始することの重要性を強調しています。

これらの変更は、Goプロジェクトへの新規貢献者が直面する可能性のある初期設定の障壁を取り除き、よりスムーズな貢献プロセスを促進することを目的としています。

コアとなるコードの変更箇所

diff --git a/doc/contribute.html b/doc/contribute.html
index 6c0d78549b..7a80fca012 100644
--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -7,7 +7,7 @@
 <p>
 This document explains how to contribute changes to the Go project.
 It assumes you have installed Go using the
-<a href="/doc/install">installation instructions</a> and
+<a href="/doc/install/source">installation instructions</a> and
 have <a href="code.html">written and tested your code</a>.
 (Note that the <code>gccgo</code> frontend lives elsewhere;
 see <a href="gccgo_contribute.html">Contributing to gccgo</a>.)
diff --git a/doc/install-source.html b/doc/install-source.html
index d9f9577a67..d356cdfc0a 100644
--- a/doc/install-source.html
+++ b/doc/install-source.html
@@ -150,6 +150,18 @@ Then check out the repository:</p>
 $ hg clone -u release https://code.google.com/p/go
 </pre>
 
+<h2 id="head">(Optional) Switch to the default branch</h2>
+
+<p>If you intend to modify the go source code, and
+<a href="/doc/contribute.html">contribute your changes</a>
+to the project, then move your repository
+off the release branch, and onto the default (development) branch.\n+Otherwise, skip this step.</p>
+\n+<pre>
+$ hg update default
+</pre>
+\n <h2 id="install">Install Go</h2>
 
 <p>

コアとなるコードの解説

doc/contribute.html の変更

-<a href="/doc/install">installation instructions</a> and
+<a href="/doc/install/source">installation instructions</a> and

この変更は、Goプロジェクトへの貢献方法を説明するドキュメント（contribute.html）内で、Goのインストール手順へのリンクを修正しています。以前は一般的なインストール手順（/doc/install）を指していましたが、この変更により、ソースコードからGoをインストールする手順（/doc/install/source）を直接参照するようになりました。これは、Goのソースコードに貢献する開発者が、通常はソースからGoをビルドして開発環境を構築するため、より関連性の高い情報に直接アクセスできるようにするための改善です。

doc/install-source.html の変更

+<h2 id="head">(Optional) Switch to the default branch</h2>
+
+<p>If you intend to modify the go source code, and
+<a href="/doc/contribute.html">contribute your changes</a>
+to the project, then move your repository
+off the release branch, and onto the default (development) branch.
+Otherwise, skip this step.</p>
+
+<pre>
+$ hg update default
+</pre>

この追加は、Goをソースからインストールする手順を説明するドキュメント（install-source.html）に、新しいセクションを挿入しています。このセクションは、Goのソースコードを変更してプロジェクトに貢献する開発者向けに、リポジトリをリリースブランチからデフォルト（開発）ブランチに切り替えることの重要性を説明しています。

  • <h2> タグ: 新しいセクションのタイトル「(Optional) Switch to the default branch」を定義しています。Optionalと明記することで、貢献しないユーザーにとっては必須ではないことを示しています。
  • <p> タグ: ブランチを切り替えるべき理由を説明しています。Goのソースコードを修正し、貢献する場合には、リリースブランチではなくデフォルト（開発）ブランチで作業する必要があることを明確に述べています。
  • <pre> タグと $ hg update default: Mercurialコマンドの例として $ hg update default を示し、開発者が実際にブランチを切り替えるための具体的な手順を提供しています。

この変更は、貢献者が誤ってリリースブランチで開発作業を進めてしまうことを防ぎ、Goプロジェクトへの貢献プロセスをより効率的かつエラーの少ないものにするための重要なガイダンスを提供します。

関連リンク

  • Gerrit Change-ID: https://golang.org/cl/6559043
    • これは、Goプロジェクトがコードレビューに利用しているGerritシステムにおける変更セットのIDです。Gerritは、GitやMercurialなどのバージョン管理システムと連携し、コードの変更をレビューし、承認するためのウェブベースのツールです。このリンクから、このコミットがGerrit上でどのようにレビューされ、承認されたかを確認できます。

参考にした情報源リンク

  • Mercurial (Hg) の公式ドキュメントやチュートリアル (Mercurialのブランチ管理やコマンドに関する一般的な情報)
  • Goプロジェクトの公式貢献ガイドライン (当時のGoプロジェクトの貢献プロセスに関する一般的な情報)
  • Gerrit Code Review の概要 (Gerritの役割と機能に関する一般的な情報)