Go Wiki: PackagePublishing

引言

現在您已經花了大量時間編寫、除錯和測試您的軟體包（您確實進行了測試，不是嗎？），您想釋出它，以便其他人可以 go get 您的軟體包。

首先，您需要將其託管在某個地方。三個主要的原始碼託管站點是 bitbucket (hg/git)，GitHub (git) 和 launchpad (bzr)。我建議選擇您熟悉的任何版本控制系統，或者您本地機器上已經使用該系統進行版本控制的程式碼。Git (git) 是 Go 核心儲存庫使用的版本控制系統，因此它提供了最接近的保證，即希望使用您專案的開發者將擁有正確的軟體。如果您從未用過版本控制，這些網站有一些很好的指南，您可以透過搜尋 Google “{name} tutorial” 來找到很多優秀的教程，其中 {name} 是您想學習的版本控制系統的名稱。

軟體包設定

選擇匯入路徑

您的軟體包的完整匯入路徑通常包含標識其作者的資訊（尤其是在 GitHub 等託管網站上，“github.com/kylelemons/…” 是完整匯入路徑），應始終包含專案名稱，並且如果您的開發包名稱與專案名稱不同，則應以您的開發包名稱結尾。例如，go-gypsy 專案提供了一個 yaml 包，由 Kyle Lemons 編寫，因此具有以下匯入路徑：

import "github.com/kylelemons/go-gypsy/yaml"
             ^         ^          ^     ^
             |         |          |     `-- Package name
             |         |          `-------- Project name
             |         `------------------- Author's handle
             `----------------------------- Hosting site

Go >= version 1 支援軟體包儲存庫的子目錄。

子目錄

通常，您為軟體包使用的名稱可能包含“Go”作為字首、字尾或其縮寫的一部分，您可能希望或不希望這成為實際命令或 go 原始檔中的軟體包名稱的一部分。通常，您的軟體包中可能包含庫和命令，它們不能共存於同一個目錄中。當發生這種情況時，您需要使用子目錄來構建您的儲存庫。

例如，考慮一個名為“Go-PublishingExample”的專案，它提供了一個“epub”軟體包和一個“publish”命令。目錄結構可以是：

./epub/      # Package source, all files package "epub"
./publish/   # Command source
./doc/       # Documentation which won't be downloaded
./examples/  # Example code which won't be downloaded

軟體包的匯入語句將是：

import "codesite.tld/authorName/Go-PublishingExample/epub"

通常，最好確保最後一個目錄路徑（在本例中為“epub”）與目錄中原始檔使用的軟體包名稱匹配。在這種情況下，根目錄中不包含任何可 go get 的檔案，因為二進位制檔案或軟體包都不命名為“Go-PublishingExample”。

分支和標籤

請注意，本節已過時。 下面的偽版本號適用於 Go < version 1；此外，Go 儲存庫本身現在使用 Git 而非 Mercurial。也許我們應該刪除本節。

您可以使用“go help get”和“go help importpath”獲取 go get 的最新資訊。

總的來說，Go 原始碼樹可以存在於三種基本狀態。它可以檢出到 Go Release 分支（在撰寫本文時是 r60 (在 Google Code 上) - 這是大多數使用者應該使用的），或者它可以檢出到 Go Weekly（大致每週建立一個新標籤），或者檢出到 tip（Mercurial 中最新更改的術語）。後兩者主要供 Go 語言本身的開發者或需要最新版本中尚未引入的特性或修復的開發者使用。

考慮到您可能會與團隊在尚未準備好公開發布的程式碼上繼續協作，建議您利用版本控制系統的標籤或分支功能。go get 工具支援一些特殊的標籤和分支，您可能希望使用它們來確保使用者獲得相容版本的軟體包。

  go.r60               -- A "go.r##" tag will be checked out if the user has that Go release installed
  go.weekly.2011-07-19 -- A "go.weekly.YYYY-MM-DD" tag will be checked out if the user has that weekly installed

如果安裝的標籤不匹配，go get 會嘗試回退到上一個標籤，如果沒有找到，則預設安裝 tip。

在 Mercurial 中建立和維護您的釋出標籤：

## Create or update a release tag
hg tag myProj-v0.0 # tag an easy-to-remember version number if you wish
hg tag go.r60 # tag this as being go release.r60 compatible

在 Git 中建立和維護髮布分支：

## Create a release branch
git tag myProj-v0.0     # Tag an easy-to-remember version number if you wish
git checkout -b go.r60  # create a release branch
git checkout master     # to switch back to your master branch

## Update the release branch
git checkout go.r60  # switch to the release branch
git merge master     # merge in changes from the master branch since last release
git checkout master  # switch back to master branch

如果您使用其他分支名稱，請將這些名稱替換到相應的位置。

通常不需要維護每週標籤或分支，但維護髮布分支或標籤可能非常有益，因為這將確保您的專案獲得最廣泛的受眾。

命令與軟體包

由於 go get 不使用您專案的 Makefiles，因此瞭解它將如何實際構建您的專案非常重要。

同一個目錄中的所有檔案應始終共享相同的軟體包名稱。任何命名帶有 `_test` 或 `_os` 和/或 `_arch` 字尾的檔案都將被忽略（除非 os/arch 匹配）。如果軟體包名稱是“main”，go get 將從原始檔構建一個可執行檔案，並根據目錄名稱（僅使用最後一個路徑段）對其進行命名。如果軟體包名稱是其他任何名稱，go get 將將其構建為軟體包，匯入路徑將是您專案根目錄的 Web 可訪問 URL，後跟子目錄。有關如何為除主要四個網站之外的程式碼託管站點建立匯入路徑的資訊，請參閱 go get 文件。

同一專案中的軟體包之間的依賴關係很常見。當您專案中的某個軟體包或命令依賴於另一個軟體包或命令時，您必須使用完整的匯入路徑，以便 go get 能夠識別該依賴關係並確保其被構建。如果您的專案中的原始檔匯入了第三方軟體包，go get 也會自動下載並安裝這些第三方軟體包（如果它們尚未安裝）。

為了重用上面的示例，檔案 `./publish/main.go` 可能看起來像這樣：

package main

import (
    "flag"
)

import "codesite.tld/authorName/Go-PublishingExample/epub"

var dir = flag.String("dir", ".", "Directory to publish")

func main() {
    flag.Parse()
    epub.Publish(*dir)
}

想要安裝此可執行檔案的使用者將執行：

go get codesite.tld/authorName/Go-PublishingExample/publish

由於依賴關係，這也會安裝 `".../epub"` 軟體包。僅想安裝庫的開發者可以執行：

go get codesite.tld/authorName/Go-PublishingExample/epub

（如果他們尚未安裝 `publish`），並且只會下載並安裝軟體包。請注意，在任何這些情況下，示例或文件都不會被下載；在大多數情況下，它們都可以透過程式碼網站進行瀏覽。

文件

godoc

當您準備釋出軟體包時，您應該透過執行本地 godoc 副本來確保文件看起來正確。如果您的軟體包已安裝到 go 軟體包樹中，您可以使用以下命令：

  godoc -http=:6060 &

然後瀏覽到 https://:6060/pkg/ 並找到您的軟體包。

Dashboard

Go Dashboard 將使用您的軟體包級別註釋的第一行（也使用普通的 godoc 格式）作為“info”文字，因此請確保已設定。例如：

// Package epub is an example publishing library.
package epub

有關 godoc 的更多資訊，請參閱 Documenting Go Code 部落格文章。