使用 git 操作網站原始碼

介紹

Git 是一個版本控制系統,用於幫助在同一份資料上的多人協作。每個用户都可以擁有主存儲庫的本地副本。本地副本可以位於同一台電腦上,也可以位於世界各地。然後,用户可以根據需要修改本地副本,並在完成資料的修改後,提交更改並將其推回主存儲庫。

如果遠程倉庫有比您在同一個分支上的本地副本新的提交(修改),則 Git 不允許您直接推送提交。如果發生衝突,請先獲取並更新您的本地副本,然後在最新提交的基礎上根據需要rebase您的新修改。

Git 存儲庫寫入權限

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

不受限制的寫入權限

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

如果您剛開始參與 Debian 網站開發,並且沒有經驗,請在請求不受限制的寫入訪問權限之前發送一封帶有自我介紹的電子郵件到 debian-www@lists.debian.org。請考慮在自我介紹中提供一些有用的信息,例如您打算翻譯哪種語言或網站的哪個部分,以及誰會為您擔保。

透過合併請求(Merge Requests)寫入存儲庫

如果您不打算獲得對存儲庫的不受限制的寫入權限或無法做到這一點,您可以隨時提交合並請求,並讓其他開發人員檢查並接受您的成果。請使用由 Salsa GitLab 平台透過其網頁介面提供的標準程序提交合並請求(閲讀 Project forking workflow 以及 When you work in a fork 瞭解詳細步驟)。

並不是所有的網站開發人員都隨時查看合併請求,因此他們不一定總是及時處理。如果您不確定所作的貢獻是否會被接受,請發送電子郵件至 debian-www 通信論壇請求核查。

使用存儲庫開展工作

獲取一份本地副本

首先,您需要安裝 git 才能使用存儲庫。接下來,在您的電腦上設置您的用户名和電子郵件信息(請參閲通常的 git 文件以瞭解如何執行此操作)。然後,您可以採用以下兩種方式之一克隆存儲庫(換句話説,對其創建本地副本)。

建議使用 webwml 的方法是先在 salsa.debian.org 上註冊一個帳户,並透過將 SSH 公鑰上傳到您的 salsa 帳户來啟用 git SSH 訪問。有關如何執行此操作的更多詳細信息,請參見 salsa 幫助頁面。然後,您可以使用以下命令克隆 webwml 存儲庫:

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

如果您還沒有 Salsa 帳號,您可以使用 HTTPS 協議克隆並獲取倉庫副本:

  git clone https://salsa.debian.org/webmaster-team/webwml.git

這將為您提供相同的存儲庫本地副本,但是您將無法直接以這種方式將修改直接推送回遠程倉庫。

克隆整個 webwml 存儲庫將需要下載大約 500MB 的數據,因此對於網絡連接緩慢或不穩定的用户而言可能會很麻煩。您可以先嚐試以最小深度進行淺克隆,以進行較小數據的初始下載:

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

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

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

檢出部分內容

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

   $ git clone --no-checkout git@salsa.debian.org:webmaster-team/webwml.git
   $ cd webwml
   $ git config core.sparseCheckout true
   在 webwml 中: 創建帶有像這樣內容的文件 .git/info/sparse-checkout :
   (如果您只想要基本文件、英語、加泰羅尼亞語和西班牙語翻譯):
      /*
      !/[a-z]*/
      /english/
      /catalan/
      /spanish/
   然後:
   $ git checkout --

提交本地修改

令您的本地倉庫保持最新

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

   git pull

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

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

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

編輯英語文件的示例

此處提供了有關於如何在網站原始碼存儲庫中編輯英語文件的示例。在使用“git clone”獲取存儲庫的本地副本之後,也在開始編輯工作之前,運行以下命令:

   $ git pull

現在對文件進行修改。當您完成後,使用以下命令將您的更改提交到本地存儲庫:

   $ git add path/to/file(s)
   $ git commit -m "Your commit message"

如果您有對遠程 webwml 存儲庫的不受限制的寫入權限,那麼現在可以將您所做的更改直接推送到 Salsa 存儲庫中:

   $ git push

如果您無權直接寫入 webwml 存儲庫,請考慮使用 Salsa GitLab 平台提供的“合併請求”功能提交您的更改,或尋求其他開發人員的幫助。

這是有關於如何使用 git 操作 Debian 網站原始碼的非常基本的概述。有關 git 的更多信息,請閲讀 git 的文件。

在 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 更新 translation-check 頭:

  1. 對原始文件進行更改,然後提交
  2. 更新翻譯
  3. 運行 smart_change.pl——它會獲取更改並更新已翻譯文件的頭
  4. 查看更改(例如,使用“ git diff”)
  5. 提交翻譯更改

或者,如果您要使用帶有正則表達式的 smart_change 來一次性對文件進行多個更改:

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

這比前一個方法涉及更多的提交(需要兩次提交),但由於 git 提交的哈希值的工作方式,這無法避免。

獲取通知

接收提交通知

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

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

接收合併請求通知

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