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

このコミットは、Goプロジェクトへの貢献方法を説明するドキュメント doc/contribute.html を更新し、Issue Trackerにおける「特別な記述（special sentences）」に関する詳細情報へのリンクを追加するものです。具体的には、コミットメッセージに特定のキーワードを含めることで、関連するIssueが自動的に更新される仕組みについて、Google Project HostingのIssue Trackerドキュメントへの参照を追加しています。

コミット

doc/contribute: Link to IssueTracker docs for more "special sentences"

Update #4582.

R=nigeltao, dave, adg
CC=golang-dev
https://golang.org/cl/7070065

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

https://github.com/golang/go/commit/7d403871cb7e319cb1f52ce2ff04c80bdc5ac92a

元コミット内容

commit 7d403871cb7e319cb1f52ce2ff04c80bdc5ac92a
Author: Matthew Dempsky <mdempsky@google.com>
Date:   Thu Jan 10 14:17:20 2013 +1100

    doc/contribute: Link to IssueTracker docs for more "special sentences"
    
    Update #4582.
    
    R=nigeltao, dave, adg
    CC=golang-dev
    https://golang.org/cl/7070065
---
 doc/contribute.html | 2 ++\n 1 file changed, 2 insertions(+)\n
diff --git a/doc/contribute.html b/doc/contribute.html
index 94409a80bf..b9e268a99f 100644
--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -266,6 +266,8 @@ The special sentence &ldquo;Fixes issue 159.&rdquo; associates
 the change with issue 159 in the <a href=\"http://code.google.com/p/go/issues/list\">Go issue tracker</a>.
 When this change is eventually submitted, the issue
 tracker will automatically mark the issue as fixed.
+(These conventions are described in detail by the
+<a href=\"http://code.google.com/p/support/wiki/IssueTracker#Integration_with_version_control\">Google Project Hosting Issue Tracker documentation</a>.)
 </p>

 <p>

変更の背景

このコミットは、Goプロジェクトの貢献ガイドラインを改善することを目的としています。特に、コミットメッセージに特定の「特別な記述（special sentences）」を含めることで、GoのIssue Tracker（当時はGoogle CodeのIssue Trackerを使用）が自動的に関連するIssueの状態を更新する機能について、より詳細な情報源へのリンクを提供しています。

コミットメッセージにある「Update #4582.」は、この変更がIssue 4582に対応するものであることを示しています。Issue 4582は、おそらくこのドキュメントの明確性や情報不足に関するものであったと推測されます。この変更により、Goプロジェクトに貢献しようとする開発者が、コミットとIssueの連携に関する規則をより深く理解できるようになります。

前提知識の解説

Issue Tracker (課題追跡システム)

Issue Trackerは、ソフトウェア開発プロジェクトにおいて、バグ、機能要求、タスク、その他の課題を記録、追跡、管理するためのシステムです。開発チームはIssue Trackerを使用して、作業の進捗状況を把握し、優先順位を付け、担当者を割り当て、課題の解決を効率的に進めます。Goプロジェクトでは、かつてGoogle CodeのIssue Trackerを利用していました。

バージョン管理システムとIssue Trackerの連携

多くのIssue Trackerは、GitやMercurialのようなバージョン管理システムと連携する機能を持っています。これにより、開発者はコミットメッセージに特定のキーワードや形式を含めることで、関連するIssueの状態を自動的に更新したり、コミットとIssueを紐付けたりすることができます。例えば、「Fixes #123」のような記述をコミットメッセージに含めることで、コミットがプッシュされた際にIssue #123が自動的に「解決済み」や「クローズ」の状態に移行する、といった連携が可能です。

Google Project Hosting Issue Tracker

Google Project Hostingは、かつてGoogleが提供していたオープンソースプロジェクト向けのホスティングサービスで、バージョン管理システム（Subversion, Git, Mercurial）、Issue Tracker、Wikiなどの機能を提供していました。Goプロジェクトも初期にはこのプラットフォームを利用していました。Google Project HostingのIssue Trackerは、コミットメッセージ内の特定のパターンを認識し、関連するIssueを自動的に更新する機能を持っていました。このコミットで参照されている「special sentences」とは、まさにこの自動連携を可能にするための特定の記述形式を指します。

技術的詳細

このコミットは、Goプロジェクトの公式ドキュメントの一部である doc/contribute.html ファイルに対する変更です。このファイルは、Goプロジェクトにコードを貢献するためのガイドラインを記述しており、パッチの作成方法、コミットメッセージの書き方、コードレビュープロセスなど、多岐にわたる情報を提供しています。

変更の核心は、コミットメッセージにおける「Fixes issue N」のような「特別な記述」に関する説明を補強することです。以前のバージョンでは、この記述がIssue Trackerと連携してIssueを自動的にクローズする機能があることのみが述べられていました。しかし、このコミットでは、その「慣習（conventions）」がGoogle Project HostingのIssue Trackerドキュメントに詳細に記述されていることを明示し、そのドキュメントへの直接リンクを追加しています。

これにより、Goプロジェクトに貢献する開発者は、単に「Fixes issue N」と書けばよいというだけでなく、その背後にあるIssue Trackerの連携メカニズムや、その他の関連する「特別な記述」について、より深く理解するための公式情報源にアクセスできるようになります。これは、ドキュメントの網羅性と利便性を向上させる上で重要な改善です。

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

--- a/doc/contribute.html
+++ b/doc/contribute.html
@@ -266,6 +266,8 @@ The special sentence &ldquo;Fixes issue 159.&rdquo; associates
 the change with issue 159 in the <a href=\"http://code.google.com/p/go/issues/list\">Go issue tracker</a>.
 When this change is eventually submitted, the issue
 tracker will automatically mark the issue as fixed.
+(These conventions are described in detail by the
+<a href=\"http://code.google.com/p/support/wiki/IssueTracker#Integration_with_version_control\">Google Project Hosting Issue Tracker documentation</a>.)
 </p>

 <p>

コアとなるコードの解説

このコミットでは、doc/contribute.html ファイルの266行目付近に2行が追加されています。

追加されたHTMLコードは以下の通りです。

+(These conventions are described in detail by the
+<a href=\"http://code.google.com/p/support/wiki/IssueTracker#Integration_with_version_control\">Google Project Hosting Issue Tracker documentation</a>.)

このコードは、既存の段落の最後に、Issue Trackerの「特別な記述」に関する慣習が、Google Project HostingのIssue Trackerドキュメントに詳細に記述されていることを示すテキストと、そのドキュメントへのハイパーリンクを追加しています。

具体的には、以下の要素が含まれています。

These conventions are described in detail by the: この慣習が詳細に記述されていることを示すテキスト。
<a href=\"http://code.google.com/p/support/wiki/IssueTracker#Integration_with_version_control\">...</a>: Google Project HostingのIssue Trackerドキュメント内の「Integration with version control」セクションへのリンク。これにより、ユーザーは直接関連する情報にアクセスできます。

この変更により、Goプロジェクトへの貢献者は、コミットメッセージとIssue Trackerの連携に関するより深い理解を得るための公式リソースに簡単にアクセスできるようになり、ドキュメントの質が向上しました。

参考にした情報源リンク

Go project's issue tracker conventions: https://go.dev/s/issue-tracker-guidelines (現在のGoプロジェクトのIssue Trackerガイドライン)
Google Project Hosting Issue Tracker documentation (archived resources):
- https://github.io/google/google-code-archive/
- https://developers.google.com/issue-tracker/ (現在のGoogle Issue Trackerに関する情報)
GoプロジェクトのIssue Trackerにおける「special sentences」に関する情報（検索結果より）：

comemo