工作流程訣竅和問題

工作流程提示

以下提示可以協助您在 Fuchsia 上工作時提高效率。

安裝 Gerrit Monitor

安裝 Gerrit Monitor Chrome 擴充功能，在 Chrome 工具列中加入需要您留意的 Gerrit 變更清單。

最佳化您的 Gerrit 設定

請查看Gerrit 設定，並視需要進行調整。例如，您可能會想要啟用「在推送時發布留言」，讓系統在發布新修補程式集時自動傳送草稿留言，您無須透過網頁版 UI 手動執行這項操作。

在 Git 中啟用三向差異功能

根據預設，Git 在進行簡報衝突時會使用雙向差異。但不會顯示衝突前的原始文字，因此「難以解決部分衝突」。

您可以啟用三向差異功能，將 Git 設為顯示原始文字：

git config --global merge.conflictstyle diff3

啟用 fuchsia 專用 Git 指令

將 $FUCHSIA_DIR/scripts/git 新增至 PATH，以便使用 fuchsia 專用 Git 指令，例如 git fuchsia-review [<commit ref>]，以 gerrit 開啟目前或指定的修訂版本。

問與答

建議您在此加入自己的問題和答案！

問： Fuchsia 有標準 Git 工作流程嗎？

Fuchsia 團隊會使用各式各樣的工作流程。您應開始使用的每日工作流程如下：

$ jiri update -gc
# Start a new feature on a `myfeature` branch from the current stable commit
$ git checkout -b myfeature JIRI_HEAD
# Do work, making changes, etc.
$ git commit
# Upload your work to Gerrit for review
$ jiri upload
# OR
$ git push origin HEAD:refs/for/main

恭喜，您完成了第一次的 Gerrit 變更！

假設您在等待 myfeature 分支版本上的工作審核完成時，想在 otherfeature 分支版本上開始新的工作：

# Start a new independent line of work on the `otherfeature` branch
# while waiting for review of `myfeature`:
$ git checkout -b otherfeature JIRI_HEAD
# OR
# Start a derivative line of work while waiting for review:
$ git checkout -b otherfeature

當您想要更新 myfeature 分支版本，但已在 otherfeature 分支版本上處理一個「獨立」的工作行時：

# Commit any present dirty work, then, switch to "myfeature":
$ git checkout myfeature
# Make any relevant edits to the code, then:
$ git commit --amend
# Now upload the new patchset to Gerrit:
$ jiri upload
# OR
$ git push origin HEAD:refs/for/main

當您收到一些評論留言，且使用「衍生」的工作行而想要更新 myfeature 分支版本時，請按照以下步驟操作：

# Now you get a review comment that needs a change in "myfeature"
# Commit your present work, if you aren't finished, maybe use a work-in-progress change:
$ git commit -a -m "work in progress"
# Start a rebase operation, so you can edit your first change:
$ git rebase -i JIRI_HEAD
# Replace "pick" with "edit" on the change you need to update and save and close the file
# Make the relevant code changes, then:
$ git add . && git rebase --continue
# You may need to make additional "rebase" steps if your edits need integration
# with later commits For each case, look at "git status" to see what files are
# in conflict, and make the relevant adjustments. The rebase is complete when
# git reports "Successfully rebased and updated ...." If you made a "work in
# progress" change and want to unwind that commit:
$ git reset HEAD
# Now you can upload your modified changes to Gerrit:
$ jiri upload
# OR
$ git push origin HEAD:refs/for/main

如果您在 Gerrit 中看到「merge 衝突」，因為您的變更無法明確與 main 分支版本整合：

# Checkout the branch for the change you need to update (e.g. "myfeature"):
$ git checkout myfeature
# Update your git repository:
$ git fetch
# Update your branch:
$ git rebase origin/main
# Fixup and continue the rebase as necessary, until you see "Successfully rebased ..."
# Then upload your newly updated code:
$ jiri upload
# OR
$ git push origin HEAD:refs/for/main

如果您工作了超過一天，且需要與上游「同步處理程式碼」(通常每天至少執行一次)：

# Commit any in-progress work, then
# Checkout the stable upstream you last sync'd
$ git checkout JIRI_HEAD
# Update your local repository (this will include updates for prebuilts, third
# party repositories, and so on):
$ jiri update -gc
# Now to switch back to, and update your working branch (e.g. "myfeature"):
$ git checkout myfeature
# Updating "myfeature" with the latest stable code:
$ git rebase JIRI_HEAD
# Perform fixups and "git rebase --continue" until you get to "Successfully rebased ..."

如要進一步瞭解工作流程的各個部分，請參閱下文。如要進一步瞭解一般 Git 工作流程，請參閱 gitworkflows(7)。如要進一步瞭解 Git 的一般概念，請前往 git-scm.com/doc。

重低音

同時更新所有專案，並在 JIRI_HEAD 重新建構工作分支版本：

$ jiri update -gc -rebase-untracked
$ git checkout <my_branch>
$ git rebase JIRI_HEAD

git rebase 到 JIRI_HEAD 應在已執行工作的「每個」存放區中完成。但您尚未處理過的存放區。

上傳變更的新修補程式集 (快照)

您必須將修補程式集上傳為 Gerrit，才能讓其他使用者審查。我們要使用 jiri upload。

Gerrit 會在變更說明中使用自動產生的中繼資料標記，找出要將修補程式上傳至哪個 Gerrit 審查執行緒，例如：Change-Id: I681125d950205fa7654e4a8ac0b3fee7985f5a4f

這與 Git 修訂版本的 SHA 雜湊不同，可在審查期間視為穩定，因為當您編輯變更和修訂。針對特定評論使用相同的變更 ID (假設您要壓縮多個修訂版本)。

如果您已變更修補程式集，並想上傳新的修補程式集，那麼 (假設這是分支的最新變更；使用 git log 找出) 可以執行類似操作：

$ git commit -a --amend
# -a for all uncommitted files, --amend to amend latest commit
$ jiri upload

解決合併衝突

嘗試重新基數：

$ git fetch origin && git rebase origin/main
# Resolve conflicts as needed...
$ jiri upload

但請參閱下方說明，瞭解 git rebase 如何排除與 jiri update 的互動。

隱藏

您可以保留所有未提交的變更，稍後再重新套用。 當您開始使用 Git 時，這項功能通常很實用。

$ git stash # uncommitted changes will go away
# do stuff
$ git stash pop # uncommitted changes will come back

答：兩者之間並無關聯。jiri 是 Git 的包裝函式，可以支援同步處理多個 Git 存放區 (Fuchsia 程式碼集由許多 Git 存放區組成)，以及同步處理一組預先建構的構件 (例如在 //prebuilt 中找到的構件)。fx 是許多內建於 Fuchsia 樹狀結構中工具的便利包裝函式，可協助執行許多日常工作流程工作，例如建構、執行測試、使用記錄檔、連線至裝置上的殼層等許多作業。

問：將 Git 重組對應至 origin/main 後，存放區的 jiri-updated (亦即同步處理) 檢視畫面會受到影響嗎？

答：可以，除非 jiri 設為同步處理重新編寫的存放區/永久版本，而非與全球整合版本保持同步。如果您使用目前/新的預設 Bootstrap 設定，並追蹤所有存放區的全域整合作業，就屬於這種情況。不過，如果您過去曾設定結帳功能或使用 fx set-petal X，就有可能發生這種情況。

在 petal X 一起工作 (加上 fx set-petal X) 時，jiri update 會將存放區 X 中的本機分支版本重新建構到來源/main 的 HEAD 上。但其他寵物存放區會同步處理至可能位於來源/主目錄 HEAD 的特定修訂版本。

Fuchsia 的持續整合系統 (特別是滾輪) 會在測試新的修訂版本不會破壞其他花瓣的情況下，向其他花瓣提供新的花瓣。jiri update 將一律讓其他花瓣與這些成功測試的修訂版本保持同步。但是，針對寵物的 Git 重組，可能會推進該存放區以外的已測試版本，因而可能造成破壞性變更。結果可能是您可以為特定花瓣進行建構，但無法針對其他花瓣進行建構 (例如正確建構垃圾，但無法建構頂級)。

如果您有想要使用 Jiri 的特定修訂版本，請下載其 jiri.update 檔案並將其動態饋給至 jiri update。

問：如果我需要跨 Git 存放區的不可部分修訂版本，該怎麼辦？

答：很抱歉，請試著排列變更內容，以免在轉場期間使每個經歷中斷 (即進行柔性轉換)。但有時您必然會遇到破損情況；目標就是盡量縮短破壞時間 (即「硬轉換」)。

範例情境：我在 stem 中定義了介面，再於另一個花瓣中實作。如果我更換介面，是否就會破壞其他花瓣？

可以。但您可以「照顧」滾動工具，盡量縮小中斷範圍。以保育的注意事項是，其他人「也」可能會感到破壞，導致懷孕的時間超過預期。

您也可以採用以下做法：

  1. 在 lower 中引入新的介面，這是原始介面的副本。
  2. 等待 lower-roller 新增至 upper，或藉由更新 upper/manifest 檔案自行擲骰子。
  3. 變更 upper，以便使用維護舊合約的新本機副本介面。
  4. 變更 lower，將原始介面的合約修改為所需新格式。
  5. 等lower-roller或自己去擲骰子。
  6. 將 upper 變更為使用原始介面名稱，現在有新合約。並視需要修改。
  7. 刪除 lower 中的複製介面。

問：如何從一組來源進行平行建構？

假設您想要產生四個版本：

  • x64 的「啟動」產品
  • 適用於 x64 的「極簡版」產品
  • vim3 的「核心」產品
  • vim3 的「minimal」產品

首先，您必須建構 Zircon，因為 Zircon 建構目錄會與 Fuuchsia 建構目標共用。快要選擇哪個產品/主機的組合，我們只需要開始建構 Zircon。

# We start with bringup, because it's small, but it doesn't matter which you start with:
$ fx --dir out.bringup.x64 set bringup.x64
$ fx --dir out/bringup.x64 build

您已成功建構 Zircon，現在可以開始同時建構其他幾個版本：

$ fx --dir out/minimal.x64 set minimal.x64
$ fx --dir out/minimal.x64 build > minimal.x64.build.log &

$ fx --dir out/core.vim3 set core.arm64
$ fx --dir out/core.vim3 build > core.vim3.build.log &

$ fx --dir out/minimal.vim3 set minimal.arm64
$ fx --dir out/minimal.vim3 build > minimal.vim3.build.log &

在執行 fx 工具時，您可以將 --dir 傳遞至 fx 指令 (例如，使用 vim3 最低產品執行 fx serve)，以便參照每個版本，您可以使用：

$ fx --dir out/minimal.vim3 serve

您也可以利用 fx use 變更目前預設的建構目錄：

$ fx use out/core.vim3

問：如果使用先前的快照建構存放區中的舊快照，該怎麼做？

答：您需要針對 jiri 快照檔案 jiri update，這是一個 XML 檔案，可擷取 jiri 追蹤的每個存放區狀態。

問：如何取得適用於特定 fuchsia.git 修訂版本的版本？

答：fx sync-from-stem 會進行這項操作。實際上使用 jiri。然而，系統不會為了比對目前的整合存放區而同步處理 fuchsia.git 和依附元件，而是會尋找與「目前查核」 fuchsia.git 相符的整合修訂版本，並同步處理整合與依附元件以符合該 fuchsia.git 修訂版本。

換句話說，fuchsia.git 將維持不變，而其他所有內容都會保持同步。這有助於在 fuchsia.git 內移動。

問：我在 Mac 上進行建構，如何避免看到「即將傳入的網路連線」通知出現垃圾內容？

答：您想要執行 fx setup-macos，透過 macOS 應用程式防火牆註冊所有相關的 Fuchsia 工具。

問：變更 API 時，何時/如何進行軟性或強制轉換？

請參閱本節，瞭解硬式編碼和軟轉換。

問：如何更新 FIDL 通訊協定？

答：更新 FIDL 通訊協定的建議做法是使用軟轉換。為了讓軟性轉換作業順利運作，您必須建立同時支援舊版與新版通訊協定的中繼狀態。

請按照下列步驟執行軟性轉換：

  1. 修改 Stem 存放區中的 FIDL 定義，以支援新舊通訊協定元素。到達變更之前，請觸發全域整合工作嘗試驗證步驟 2 是否成功。

  2. 等待每日自動發布，或是手動發布存放區，即可發布 Stem 存放區。

  3. 更新所有用戶端，使其使用新的通訊協定元素。

  4. 發布所有用戶端。

  5. 從 Stem 存放區的 FIDL 定義中移除舊通訊協定元素。

  6. 發布 Stem 存放區，通常需要等待每日自動發布。

問：如何協調多個花瓣的變動？

答：在多個花瓣上 (或在 Stem 存放區與一或多個花瓣之間) 協調不可部分的變更，就需要執行「硬性轉換」。

請按照下列步驟執行強制轉換：

  1. 準備對所有受影響的存放區做出變更。如果這些存放區全都屬於「平台來源樹狀結構」：

    1. 將相關變更上傳至 fuchsia-review.googlesource.com。
    2. 上傳另一項修改全域整合存放區的變更，以便參照您變更中的 Git 修訂版本。對這個 Gerrit 變更的修訂佇列執行「模擬測試」。

  2. 通知專責團隊，表示您打算執行硬性轉換作業。

  3. 完成受影響存放區中的所有變更。這個步驟會中斷這些存放區的本機整合作業，但不會破壞全域整合，因為變更尚未發布。

  4. 在「全域整合」存放區中進行變更，藉此參照受影響存放區的新版本。這項變更將發布所有受影響存放區的新版本，而且不會中斷全域整合作業。這項變更應在受影響的存放區中取消本機整合作業。

問：如何開啟歷史記錄，以便追蹤在發生變化時的情況？

答：如要濃縮記錄，請執行下列步驟：

  1. 根據可觀察的變更前後，在設定存放區中提供記錄，其中包含全域整合的修訂版本記錄。這個筆記本的結果會是設定存放區的單次變更，這假設包含一或多個存放區或預先建構套件的發布作業。

  2. 如果設定存放區的變更是針對單一存放區發布，請在全域整合發布前後建立該存放區的記錄。這個字型的結果應該是行為發生變化的修訂版本。

  3. 如果設定存放區的變更是針對預先建構套件的發布項目，請切換至建立預建套件的來源樹狀結構。請參閱該存放區的說明文件，瞭解如何在該存放區導入變更。

  4. 如果設定存放區的變更是同時發布多個存放區，由於這兩個存放區可能在協同作業中有所變更，而您也需要跨越整個存放區記錄變更，因此合併記錄會變得複雜。建議您查看存放區的記錄，瞭解一起發布存放區的原因。

問：我可以在不複製存放區的情況下搜尋 Fuchsia 原始碼嗎？

答：當然可以！基本存放區提供導覽的「Gitiles」使用者介面。您也可以使用 Google 開放原始碼搜尋工具，在線上瀏覽及搜尋 Fuchsia 程式碼集。