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

このコミットは、Goプロジェクトの貢献ガイドライン (doc/contribute.html) に、変更を加える前にMercurial (hg) の default ブランチに更新するよう指示を追加するものです。これにより、貢献者が誤ってリリースブランチで作業を進めてしまうことを防ぎ、変更が適切なブランチに適用されるように促します。

コミット

commit 3238705f0cd7266e20b5d55d8659069c4c702aad
Author: Andrew Gerrand <adg@golang.org>
Date:   Tue Jun 5 00:55:45 2012 +1000

          doc: mention 'hg update default' in contribution guidelines
    
    Fixes #3634.
    
    R=golang-dev, bsiegert, rsc
    CC=golang-dev
    https://golang.org/cl/6270047

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

https://github.com/golang/go/commit/3238705f0cd7266e20b5d55d8659069c4c702aad

元コミット内容

doc: mention 'hg update default' in contribution guidelines

Fixes #3634.

R=golang-dev, bsiegert, rsc
CC=golang-dev
https://golang.org/cl/6270047

変更の背景

この変更の背景には、Goプロジェクトへの貢献者が、誤ってリリースブランチ（安定版のコードベース）で作業を開始してしまうという問題があったと考えられます。多くのGoのインストールでは、安定したリリースブランチがデフォルトで利用されますが、新しい機能やバグ修正は通常、開発の最前線である default ブランチに対して行われます。

もし貢献者が default ブランチに切り替えることなく変更を加えてしまうと、その変更はリリースブランチに適用されてしまい、将来のリリースに意図せず含まれたり、default ブランチへのマージが複雑になったりする可能性があります。これを防ぐため、貢献ガイドラインに明示的に hg update default コマンドの実行を促すことで、このような混乱や作業の無駄をなくし、スムーズな貢献プロセスを確立することが目的です。コミットメッセージの "Fixes #3634" は、この問題がGitHubのIssue #3634で報告され、その解決策としてこのドキュメント更新が行われたことを示唆しています。

前提知識の解説

1. Goプロジェクトのバージョン管理システム (Mercurial)

Goプロジェクトは、かつて分散型バージョン管理システムであるMercurial (略称 hg) を主要なバージョン管理システムとして使用していました。Gitが主流となる以前は、Mercurialも多くのオープンソースプロジェクトで採用されていました。MercurialはGitと同様に、リポジトリのクローン、ブランチの作成、コミット、マージなどの機能を提供します。

2. Mercurialのブランチと `default` ブランチ

Mercurialには、複数の開発ラインを管理するためのブランチ機能があります。Goプロジェクトでは、主に以下のブランチが使われていました。

default ブランチ: これはMercurialにおける「メイン」または「開発」ブランチに相当します。新しい機能開発やバグ修正は、通常このブランチに対して行われます。Gitにおける main や master ブランチに似ています。
リリースブランチ: 特定のGoのバージョン（例: release-go1.0）に対応するブランチです。これらのブランチは安定版のコードを保持し、主にバグ修正やセキュリティパッチが適用されます。

3. `hg update` コマンド

hg update コマンドは、Mercurialリポジトリの作業ディレクトリを指定したリビジョンやブランチの状態に更新するために使用されます。

hg update <リビジョン>: 指定されたリビジョンの状態に作業ディレクトリを更新します。
hg update <ブランチ名>: 指定されたブランチの最新の状態に作業ディレクトリを更新します。

したがって、hg update default は、作業ディレクトリを default ブランチの最新の状態に切り替えることを意味します。これは、Gitにおける git checkout main や git switch main に相当する操作です。

4. オープンソースプロジェクトへの貢献ワークフロー

一般的なオープンソースプロジェクトへの貢献ワークフローでは、以下のステップが踏まれます。

リポジトリのクローン: プロジェクトのリポジトリをローカルにコピーします。
ブランチの切り替え/作成: 変更を加えるための新しいブランチを作成するか、適切な開発ブランチに切り替えます。
変更の実施: コードの修正や新機能の追加を行います。
コミット: 変更をローカルリポジトリに記録します。
プッシュ: 変更をリモートリポジトリに送信します（通常はフォークしたリポジトリ）。
プルリクエスト/変更リクエストの作成: 変更を本家リポジトリにマージしてもらうためのリクエストを送信します。

このコミットは、ステップ2において、特にMercurialを使用している場合に default ブランチへの切り替えを明示的に促すことで、貢献プロセスをよりスムーズかつ正確にするためのものです。

技術的詳細

このコミットは、Goプロジェクトの貢献ガイドラインを記述したHTMLファイル doc/contribute.html に、新しいセクションを追加することで、Mercurialの default ブランチへの切り替えを明示的に指示しています。

追加されたセクションは <h3>Switch to the default branch</h3> という見出しで始まり、以下の内容を含んでいます。

目的の明確化: 「ほとんどのGoのインストールはリリースブランチを使用しますが、新しい変更は default ブランチに対してのみ行われるべきです。」と説明し、なぜ default ブランチで作業する必要があるのかを明確にしています。これは、リリースブランチが安定版であり、新しい開発は常に最先端の default ブランチで行われるというプロジェクトのポリシーを反映しています。
理由の補足: 「（それらの変更は、リリースプロセスの一部として後でリリースブランチに適用される可能性があります。）」と補足することで、default ブランチで行われた変更が最終的にリリースブランチにも反映されるメカニズムを示唆しています。
具体的な手順: 「変更を加える前に、default ブランチを使用していることを確認してください。」と指示し、そのための具体的なコマンド hg update default を pre タグで囲まれたコードブロックとして提供しています。これにより、ユーザーはコマンドを簡単にコピー＆ペーストして実行できます。

この変更は、単なるドキュメントの追加ですが、プロジェクトの貢献ワークフローにおける重要なステップを明文化することで、以下のような技術的なメリットをもたらします。

ブランチの整合性: 貢献者が常に正しいブランチ（default）で作業することを保証し、意図しない変更がリリースブランチに混入するリスクを低減します。
マージの簡素化: default ブランチで作業された変更は、他の開発中の変更と競合する可能性が低く、マージプロセスがよりスムーズになります。もしリリースブランチで作業された場合、default ブランチへのバックポートやマージが複雑になる可能性があります。
開発サイクルの効率化: 貢献者が正しいブランチで作業することで、レビュー担当者やメンテナがブランチの不一致による問題を解決する手間が省け、全体的な開発サイクルが効率化されます。
新規貢献者のオンボーディング: 特にMercurialに不慣れな新規貢献者にとって、どのブランチで作業すべきか、どのように切り替えるべきかという明確な指示は、プロジェクトへの参加障壁を低減します。

このドキュメントの更新は、コードベースそのものに直接的な機能変更をもたらすものではありませんが、プロジェクトの運用と貢献者の体験を向上させる上で非常に重要な役割を果たします。

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

変更は doc/contribute.html ファイルに対して行われています。

--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -163,6 +163,19 @@ can use that nickname as a shorthand for naming reviewers and the CC list.
 For example, <code>rsc</code> is an alias for <code>rsc@golang.org</code>.\n </p>\n \n+<h3>Switch to the default branch</h3>\n+\n+<p>\n+Most Go installations use a release branch, but new changes should\n+only be made to the default branch. (They may be applied later to a release\n+branch as part of the release process.)\n+Before making a change, make sure you use the default branch:\n+</p>\n+\n+<pre>\n+$ hg update default\n+</pre>\n+\n <h3>Make a change</h3>\n \n <p>\n```

具体的には、`doc/contribute.html` の163行目以降に、新しい `<h3>` 見出しとそれに続く `<p>` タグ、そして `<pre>` タグで囲まれたコードブロックが追加されています。

## コアとなるコードの解説

追加されたHTMLスニペットは、Goプロジェクトへの貢献ガイドラインの「変更を加える」セクションの直前に挿入されています。

1.  **`<h3>Switch to the default branch</h3>`**:
    *   これは新しいサブセクションのタイトルです。貢献者に対して、変更作業を開始する前に `default` ブランチに切り替えることの重要性を強調しています。

2.  **`<p>` タグ内の説明**:
    *   `Most Go installations use a release branch, but new changes should only be made to the default branch.`
        *   これは、多くのユーザーが安定版のGo（リリースブランチ）を使用しているという現状を説明しつつ、新しい開発は `default` ブランチで行われるべきであるというプロジェクトのルールを明確にしています。
    *   `(They may be applied later to a release branch as part of the release process.)`
        *   `default` ブランチで行われた変更が、最終的にリリースブランチにも取り込まれる可能性があることを示唆しています。これにより、貢献者は `default` ブランチで作業しても、その変更が無駄にならないことを理解できます。
    *   `Before making a change, make sure you use the default branch:`
        *   変更作業に入る前の必須ステップとして、`default` ブランチへの切り替えを確認するよう促しています。

3.  **`<pre>` タグ内のコマンド**:
    *   `$ hg update default`
        *   これは、Mercurialで `default` ブランチに切り替えるための具体的なシェルコマンドです。`<pre>` タグで囲むことで、等幅フォントで表示され、コードスニペットとして認識しやすくなっています。先頭の `$` は、これがシェルコマンドであることを示す慣例的な記号です。

この追加により、貢献ガイドラインはより明確になり、特にMercurialのブランチ管理に不慣れなユーザーでも、正しいワークフローで貢献できるようになります。これは、ドキュメントの品質向上と、プロジェクトへの貢献プロセスの円滑化に寄与する重要な変更です。

## 関連リンク

*   GitHubコミットページ: [https://github.com/golang/go/commit/3238705f0cd7266e20b5d55d8659069c4c702aad](https://github.com/golang/go/commit/3238705f0cd7266e20b5d55d8659069c4c702aad)
*   Go Code Review (Gerrit) の変更リスト: [https://golang.org/cl/6270047](https://golang.org/cl/6270047)

## 参考にした情報源リンク

特になし。コミット情報と一般的なMercurialの知識に基づいています。

Keyboard shortcuts

comemo