使用 git 進行 Debian 網站開發

使用 Git 存儲庫開展工作

讓我們直奔主題——本節中您將瞭解如何創建主存儲庫的本地副本、如何使本地副本保持最新,以及如何提交您的工作。我們也會介紹如何開展翻譯工作。

獲取一份本地副本

首先,安裝 Git。然後,配置 Git 並輸入您的姓名和電子郵件地址。如果您是 Git 的新用户,先閲讀通用的 Git 文件可能是個好主意。

下一步是克隆存儲庫(換句話説,對其創建本地副本)。有兩種方法:

提示:克隆整個 webwml 存儲庫需要下載大約 1.3 GB 的數據,如果您的網絡連接太慢或不穩定,這個數據量就太大了。所以,可以先以最小深度進行克隆,以減少首次下載的數據量:

  git clone git@salsa.debian.org:webmaster-team/webwml.git --depth 1

獲得可用的(淺)存儲庫後,您可以加深本地副本,並最終將其轉換為完整的本地存儲庫:

  git fetch --deepen=1000 # 為倉庫加深 1000 次提交
  git fetch --unshallow   # 獲取所有未獲取的提交,將倉庫轉換成完整的

您也可以僅檢出部分頁面,如下所示:

  1. git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
  2. cd webwml
  3. git config core.sparseCheckout true
  4. webwml 中創建文件 .git/info/sparse-checkout,定義您想要檢出的內容。例如,如果您只想要基本文件、英語、加泰羅尼亞語和西班牙語翻譯,文件內容應該像下面這樣:
          /*
          !/[a-z]*/
          /english/
          /catalan/
          /spanish/
        
  5. 最後,您就可以檢出庫:git checkout --

提交本地修改

令您的本地倉庫保持最新

每隔幾天(也一定要在開始一些編輯工作之前!),您應該運行一次

  git pull

以從存儲庫中獲取已被更改的文件。

強烈建議在執行 git pull 和開始編輯文件之前保持本地 Git 工作目錄的乾淨。如果您有未提交的更改,或者當前分支的遠程存儲庫中不存在的本地提交,則執行 git pull 將會自動創建合併提交,甚至會由於衝突而導致拉取失敗。請考慮將未完成的工作保存在另一個分支中,或使用 git stash 之類的命令。

注意:Git 是一個分佈式(而非集中式)版本控制系統。這意味着當您提交更改時,它們將僅存儲在本地存儲庫中。要與他人共享它們,您還需要將所做的更改推送到 Salsa 上的中央存儲庫。

示例:編輯文件

讓我們看一個更實際的例子,也就是典型的編輯過程。我們假設您已經使用 git clone 獲得了庫的一份本地副本。接下來的步驟是:

  1. git pull
  2. 現在您可以開始編輯並對文件進行修改。
  3. 當您完成後,使用以下命令將您的更改提交到本地存儲庫:
        git add /path/to/file(s)
        git commit -m "Your commit message"
        
  4. 如果您有對遠程 webwml 存儲庫的不受限制的寫入權限,那麼現在可以將您所做的更改直接推送到 Salsa 存儲庫中:git push
  5. 如果您無權直接寫入 webwml 存儲庫,請考慮使用合併請求提交您的更改,或尋求其他開發人員的幫助。

在 Git 提交中關閉 Debian 的缺陷

如果您的提交日誌條目中包含 Closes: #nnnnnn,那麼在您推送您的更改後,缺陷編號 #nnnnnn 將會被自動關閉。精確的格式與 Debian 政策中的介紹相同。

使用 HTTP/HTTPS 鏈接

許多 Debian 網站都支持 SSL/TLS,因此請儘可能使用 HTTPS 鏈接。但是,某些 Debian/DebConf/SPI 等網站要麼不具有 HTTPS 支持,要麼僅使用 SPI 數字證書認證機構(並不是一個被所有瀏覽器信任的 SSL 證書認證機構)。為了避免給非 Debian 用户帶來錯誤消息的困擾,請不要使用 HTTPS 鏈接到此類站台。

Git 存儲庫會拒絕那些包含使用純 HTTP 鏈接到支持 HTTPS 的 Debian 網站的內容或包含使用 HTTPS 鏈接到已知不支持 HTTPS 或僅使用 SPI 簽名的證書的 Debian/DebConf/SPI 網站的內容的提交。

開展翻譯工作

翻譯應始終與相對應的英文文件同步並保持最新。翻譯文件中的 translation-check 頭用於跟蹤當前翻譯所基於的英語文件的版本。如果您更改了已翻譯的文件,則需要更新 translation-check 頭以匹配英語文件中相應更改的 Git 提交哈希值。您可以使用以下命令找到該哈希值:

  git log path/to/english/file

如果您要對一個文件新建翻譯,請使用 copypage.pl 命令稿,它將為您的語言創建一個模板,該模板包含了正確的翻譯頭。

使用 smart_change.pl 進行翻譯修改

smart_change.pl 是一個命令稿,目的是讓同時更新原始文件及其翻譯更為容易。有兩種方法供您使用,選擇哪種取決於您進行的更改。

以下步驟説明了如何使用 smart_change.pl,以及當手動修改文件時,如何只更新 translation-check 頭:

  1. 對原始文件進行更改,然後提交。
  2. 更新翻譯。
  3. 運行 smart_change.pl -c COMMIT_HASH(使用對原始文件的更改產生的提交哈希值)。它會獲取該更改,並更新已翻譯文件的頭。
  4. 檢查更改(例如,使用 git diff)。
  5. 提交翻譯更改。

或者,您可以使用正則表達式來一次性對文件進行多個更改:

  1. 運行 smart_change.pl -s s/FOO/BAR/ origfile1 origfile2 ...
  2. 檢查更改(例如,使用 git diff)。
  3. 提交原始文件。
  4. 運行 smart_change.pl origfile1 origfile2(即,這次不帶正則表達式)。它就會只更新已翻譯文件的頭。
  5. 最後,提交翻譯更改。

必須承認,這比第一個例子更麻煩一點,因為涉及到兩次提交,但是,由於 Git 哈希值的工作方式,這是無法避免的。

Git 存儲庫寫入權限

整個 Debian 網站原始碼都使用 Git 管理。它位於 https://salsa.debian.org/webmaster-team/webwml。默認情況下,不允許訪客推送自己的提交到原始碼存儲庫中。如果您想要對 Debian 網站作出貢獻,您需要一些許可才能獲得對存儲庫的寫入權限。

不受限制的寫入權限

如果您需要對存儲庫的不受限制的寫入權限(例如,您打算成為頻繁提交的貢獻者),請在登錄到 Debian Salsa 平台後透過 https://salsa.debian.org/webmaster-team/webwml 網頁介面請求寫入權限。

如果您剛開始參與 Debian 網站開發,並且沒有經驗,請在請求不受限制的寫入權限之前發送電子郵件到 debian-www@lists.debian.org 介紹一下您自己。請您考慮在自我介紹中提供更多有用的信息,例如您打算對網站的哪個部分進行修改、您説哪種語言,以及是否有 Debian 團隊的其他成員可以為您擔保。

合併請求(Merge Request)

獲得對存儲庫的不受限制的寫入權限並不是必需的——您可以隨時提交合並請求,並讓其他開發人員檢查並接受您的成果。請使用由 Salsa GitLab 平台透過其網頁介面提供的標準程序提交合並請求,並請閲讀以下兩篇文件:

注意,並不是所有的網站開發人員都隨時查看合併請求,所以您可能需要等一段時間才能收到反饋。如果您不確定所作的貢獻是否會被接受,請發送電子郵件至 debian-www 通信論壇請求核查。

接收通知

如果您正在 Debian 網站上開展工作,您可能想要知道 webwml 存儲庫的動向。有兩種方法可以讓您始終處於圈子內:提交通知和合並請求通知。

接收提交通知

我們已經在 Salsa 中配置好了 webwml 項目,提交會顯示在 IRC 頻道 #debian-www 中。

如果您想要在 webwml 存儲庫中有提交時透過電子郵件接收通知,請按照以下步驟透過 tracker.debian.org 訂閲 www.debian.org 偽套件並在其中激活 vcs 關鍵字(僅需一次):

  1. 打開網頁瀏覽器並訪問 https://tracker.debian.org/pkg/www.debian.org
  2. 訂閲 www.debian.org 偽套件(如果您尚未在其它情況下使用過 tracker.debian.org,則可以使用 SSO 透過驗證或使用電子郵件和密碼進行註冊)。
  3. 跳轉到 https://tracker.debian.org/accounts/subscriptions,然後點擊 modify keywords,選中 vcs(如果其未被選中)並保存。
  4. 從現在開始,每當有人提交更改到 webwml 存儲庫時,您將收到電子郵件。

接收合併請求通知

如果您想要在 Salsa 上的 webwml 存儲庫收到新的合併請求(Merge Request)的時候得到電子郵件提醒,您可以在網頁介面上配置您的通知設置。步驟如下:

  1. 登陸您的 Salsa 帳號並前往項目頁面。
  2. 點擊項目主頁頂部的鈴鐺圖標。
  3. 選擇您所需的通知級別。