使用 git 進行 Debian 網站開發
使用 Git 存儲庫開展工作
讓我們直奔主題——本節中您將瞭解如何創建主存儲庫的本地副本、如何使本地副本保持最新,以及如何提交您的工作。我們也會介紹如何開展翻譯工作。
獲取一份本地副本
首先,安裝 Git。然後,配置 Git 並輸入您的姓名和電子郵件地址。如果您是 Git 的新用户,先閲讀通用的 Git 文件可能是個好主意。
下一步是克隆存儲庫(換句話説,對其創建本地副本)。有兩種方法:
- 在 https://salsa.debian.org 上註冊一個帳户,並透過將 SSH 公鑰上傳到您的 salsa 帳户來啓用 SSH 訪問。更多信息,請參見 Salsa 幫助頁面。然後,您可以使用以下命令克隆
webwml
存儲庫:git clone git@salsa.debian.org:webmaster-team/webwml.git
- 另一種方式是,您可以使用 HTTPS 協議克隆存儲庫。請注意,雖然這會創建一個本地副本,但是您將無法直接以這種方式將修改直接推送回遠程倉庫:
git clone https://salsa.debian.org/webmaster-team/webwml.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 # 獲取所有未獲取的提交,將倉庫轉換成完整的
您也可以僅檢出部分頁面,如下所示:
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
存儲庫,請考慮使用合併請求提交您的更改,或尋求其他開發人員的幫助。
在 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
頭:
- 對原始文件進行更改,然後提交。
- 更新翻譯。
- 運行
smart_change.pl -c COMMIT_HASH
(使用對原始文件的更改產生的提交哈希值)。它會獲取該更改,並更新已翻譯文件的頭。 - 檢查更改(例如,使用
git diff
)。 - 提交翻譯更改。
或者,您可以使用正則表達式來一次性對文件進行多個更改:
- 運行
smart_change.pl -s s/FOO/BAR/ origfile1 origfile2 ...
- 檢查更改(例如,使用
git diff
)。 - 提交原始文件。
- 運行
smart_change.pl origfile1 origfile2
(即,這次不帶正則表達式)。它就會只更新已翻譯文件的頭。 - 最後,提交翻譯更改。
必須承認,這比第一個例子更麻煩一點,因為涉及到兩次提交,但是,由於 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
關鍵字(僅需一次):
- 打開網頁瀏覽器並訪問 https://tracker.debian.org/pkg/www.debian.org。
- 訂閲
www.debian.org
偽套件(如果您尚未在其它情況下使用過 tracker.debian.org,則可以使用 SSO 透過驗證或使用電子郵件和密碼進行註冊)。 - 跳轉到 https://tracker.debian.org/accounts/subscriptions,然後點擊
modify keywords
,選中vcs
(如果其未被選中)並保存。 - 從現在開始,每當有人提交更改到
webwml
存儲庫時,您將收到電子郵件。
接收合併請求通知
如果您想要在 Salsa 上的 webwml
存儲庫收到新的合併請求(Merge Request)的時候得到電子郵件提醒,您可以在網頁介面上配置您的通知設置。步驟如下:
- 登陸您的 Salsa 帳號並前往項目頁面。
- 點擊項目主頁頂部的鈴鐺圖標。
- 選擇您所需的通知級別。