總覽
本文件說明 Fuchsia API 委員會,這是一群負責 Fuchsia API 途徑品質和長期健康狀況的人員。該委員會將與建立及修改 Fuchsia API 的人員進行建設性合作,協助引導這些 API 的演進。委員會將清楚說明其決定,包括背後的理由,並透過貢獻 Fuchsia 的 API 可讀性評分標準,記錄最佳做法。
定義
Fuchsia 系統介面是 Fuchsia 作業系統向系統上執行的軟體提供的二進位介面。舉例來說,進入 vDSO 的進入點以及系統使用的所有 FIDL 通訊協定,都是 Fuchsia 系統介面的一部分。
用戶端程式庫是指為 Fuchsia 編寫軟體的使用者可能會選擇使用的程式庫,而非直接與 Fuchsia 系統介面互動。舉例來說,FDIO 是用戶端程式庫,可在 Fuchsia 系統介面中提供類似 POSIX 的基礎 fuchsia.io 通訊協定抽象。
Fuchsia IDK 是 Fuchsia 專案為為 Fuchsia 編寫軟體的使用者提供的程式庫、中繼資料和工具集合。Fuchsia IDK 除了其他內容外,還包含 Fuchsia 系統介面的定義,以及許多用戶端程式庫。
Fuchsia API 途徑是我們在 IDK 中納入的成果集合。包括但不限於 Fuchsia 系統介面、Fuchsia IDK 中包含的用戶端程式庫、IDK 中繼資料,以及核心 Fuchsia 開發人員工具。
Fuchsia 貢獻者是指參與 Fuchsia 作業系統開發工作的人員,包括 Google 員工和非 Google 員工。
Fuchsia API 設計師是指建立或修改 Fuchsia API 途徑的人,包括 Google 員工和非 Google 員工。
最終開發人員是指撰寫使用 Fuchsia API 途徑的軟體人員。
使用者是指使用搭載 Fuchsia 作業系統的裝置的使用者。
目標
最終,Fuchsia API 委員會的目標是圍繞 Fuchsia 作業系統培養健全的軟體生態系統。要培養健全的生態系統,就必須平衡許多考量因素,包括如何擴展生態系統,以及如何引導生態系統朝特定成果發展。
值
這個生態系統有許多參與者,他們擔任許多不同的角色。在理想情況下,我們可以設計出同時滿足生態系統中所有人需求的 API,但 API 設計人員經常需要做出權衡取捨的決定。委員會應協助 API 設計人員做出這些決定,並尊重下列選民群體的優先順序:
- 使用者
- 最終開發人員
- 著作人
- API 設計人員
- 委員會成員
舉例來說,我們應設計可保護使用者隱私的 API,即使這會導致無法滿足終端開發人員的所有需求也一樣。同樣地,我們應設計更適合最終開發人員的 API,即使這些設計會對導入 API 的人員造成更大的負擔也一樣。
這些價值觀有助於引導生態系統滿足使用者需求,進而從長遠角度促進生態系統的健康與成長,因為使用者更有可能加入並留在符合自身需求的生態系統中。
策略遊戲
為了達成這些目標,委員會著重於以下指標:
功能。該委員會負責 Fuchsia API 介面的功能。具體來說,功能是指 API 是否滿足生態系統參與者的需要。舉例來說,委員會會負責確保我們的 API 能有效保護使用者的隱私權、協助最終開發人員完成特定工作,以及讓 Fuchsia 的貢獻者能隨著時間改善其實作方式。
可用性。該委員會負責 Fuchsia API 途徑的可用性。舉例來說,委員會應致力於讓 API 中類似概念的表示方式保持一致,讓終端開發人員更容易學習 API。同樣地,委員會應確保我們的 API 有完善的說明文件,且介面的語意在宣告時能讓使用者一目瞭然。
系統影響。委員會必須負責使用 Fuchsia API Surface 時對系統造成的整體負擔,包括預期和非預期的使用情形。舉例來說,使用輪詢的 API 會對系統造成沉重負擔,因為這些 API 要求用戶端持續執行,以監控條件的變化。評估系統影響力需要大量的判斷力和經驗,尤其是預測 API 的非預期用途。
溝通清楚無誤。委員會負責向 Fuchsia 貢獻者清楚說明決策,以及這些決策背後的理由。這項通訊應提供決策過程的資訊,並協助 API 設計人員瞭解如何建立高品質的 API。舉例來說,委員會應透過協助 Fuchsia 的 API 可讀性評分標準,記錄最佳做法。
客戶滿意度。該委員會負責與 API 設計人員進行有建設性的合作。委員會應營造一個環境,讓委員會成員和 API 設計師合作改善 Fuchsia API 介面。API 設計人員應將委員會視為提供正面價值的機構,協助他們打造更優質的 API,而非視為繁文縟節的負擔。舉例來說,委員會成員應迅速且禮貌地回應 API 審查要求。
會員資格
該委員會由 Fuchsia 貢獻者組成,他們已展現以下能力:
對 Fuchsia 或過去與其他平台合作的經驗,有良好的 API 品質和長期健康狀態判斷力。
具備良好的溝通和協作技能,以便與 API 設計人員 (即合作對象) 合作。
成員由專案的每個職能領域指派。
該委員會由 Fuchsia Eng Council 監督。
該委員會設有主席,由 Fuchsia 領導階層任命,負責協助 Fuchsia Eng 委員會運作。主席的職責如下:
- 安排會議。
- 設定每場會議的議程。
- 評估委員會是否已達成大致共識。
各功能負責區域
領域 | Primary | Secondary |
---|---|---|
藍牙 | jamuraa@google.com | silberst@google.com |
元件架構 | geb@google.com | dgilhooley@google.com |
開發人員 | wilkinsonclay@google.com | chaselatta@google.com |
診斷資訊 | crjohns@google.com | miguelfrde@google.com |
驅動程式 | cja@google.com | jocelyndang@google.com |
Driver SDK | jocelyndang@google.com | surajmalhotra@google.com |
體驗 | chaselatta@google.com | ianloic@google.com |
FIDL | ianloic@google.com | 無 |
韌體 | dpursell@google.com | 無 |
外部 ABI 相容性 | lindkvist@google.com | qsr@google.com |
圖形 | costan@google.com | emircan@google.com |
HCI | neelsa@google.com | emircan@google.com |
身分 | 無 | 無 |
核心 | cpu@google.com | abarth@google.com |
媒體 | dalesat@google.com | ypomortsev@google.com |
指標 | frousseau@google.com | 無 |
Netstack | brunodalbo@google.com | 無 |
電源 | mbrunson@google.com | prashanthsw@google.com |
產品組裝 | aaronwood@google.com | awolter@google.com |
安全性 | 無 | 無 |
工作階段 | quiche@google.com | neelsa@google.com |
Software Delivery | galbanum@google.com | etryzelaar@google.com |
儲存空間 | csuter@google.com | 無 |
測試 | anmittal@google.com | crjohns@google.com |
工具鍊 | mcgrathr@google.com | phosek@google.com |
查看系統 | emircan@google.com | neelsa@google.com |
虛擬化 | 無 | 無 |
網頁 | wez@google.com | ianloic@google.com |
WLAN | silberst@google.com | jamuraa@google.com |
隨著專案的演進,功能領域清單 (以及委員會的組成) 也會隨之演進。職能領域清單由 Fuchsia 領導團隊維護。
在考慮新增地區時,委員會會考量以下因素:
- 涵蓋率:這個區域是否已由其他區域涵蓋,或是有空隙?
- 範圍:這個地區是否足夠大,需要專人負責?
- 持續性需求。是否曾需要將這個區域設為區域?
決策程序
如果委員會被要求做出決策,決策程序如下所示。該地區的委員會成員是主要決策者,但委員會整體是最終決策者。委員會會根據主席的評估,以大致共識的方式做出決策。
主要決策者可以延後決定,屆時委員會將做出決定。如果委員會無法達成大致共識,主席將做出最終決定。
委員會成員可以要求委員會否決主要決策者。如果委員會無法達成大致共識,則由主要決策者做出的決定仍會維持不變。
Operations
委員會的主要功能有兩項:API 審查和 API 校正。
API 審查
任何對 Fuchsia API 途徑的變更都必須經過委員會成員核准。特定功能領域的變更通常應由負責該領域的委員會成員核准,但如果負責的委員會成員無法提供核准,任何委員會成員都可以核准變更。
除了一般 Code-Review+2 外,如果變更會修改 Fuchsia API 途徑,則在合併前,每項變更都必須接受 api-council@fuchsia.dev 成員的 API-Review+1。同一位使用者可以針對特定變更提供 API-Review+1 和 Code-Review+2。如要查看這項 Gerrit 功能的說明文件,請參閱「檢查標籤」。API 委員會成員無法為自己的 CL 給予 API-Review+1,除非這些變更是微不足道且無爭議的 (例如說明文件變更)。即便如此,我們仍鼓勵您請第二位評議會成員獨立審查。
對於小型 API 變更,尤其是對現有 API 進行漸進式精進,API 審查者通常只要進行程式碼審查,就能將變更列為 API-Review+1。不過,如果是較大的變更,尤其是會大幅擴充 API 途徑的變更,API 設計人員應撰寫 RFC (請參閱 Fuchsia RFC 範本),說明 API 設計,包括用途和範例,以及安全性和隱私權考量。即使是小幅變更,如果 API 審查者不放心僅透過程式碼審查來核准變更,也能隨時要求 API 設計人員撰寫 RFC。
如要納入 Fuchsia SDK,API 必須克服兩個障礙:必須有準備就緒且願意使用的客戶,且 API 必須經過 API 校正。
我們也鼓勵 API 設計人員向委員會成員尋求初步意見回饋。舉例來說,API 設計人員應考慮與委員會成員分享未完成的 API 設計文件,以便在設計過程初期取得意見回饋。理事會成員應參與這些討論,目標是與 API 設計人員合作,協助設計最佳 API。API 設計人員也可以在設計過程初期,向主席請求在即將舉行的 API 校正工作坊議程中留出時間,向全體委員會尋求意見回饋 (請參閱下一節)。
API 審查者應與 API 設計師合作,改善 API RFC,直到 API 審查者認為可以核准文件為止。已核准的文件可做為相關 API 的記錄計畫。不過,修改 API 途徑的個別 CL 仍須先經過 API-Review+1 審查,才能合併。API 設計人員應預期,遵循已核准的 API RFC 中所列計畫的 CL 應可輕鬆審查 API-Review+1,即使來自其他委員會成員也一樣。
API 設計人員或審查人員可以將 API RFC 提交給全體委員會,方法是請主席在即將舉行的 API 校正會議議程中安排時間 (請參閱下一節)。舉例來說,如果 API 審查員認為 API 審查結果不夠準確、API 特別複雜或重要,或是審查員因截止日期逼近或其他團隊的壓力而感到焦慮,就可能將文件交由全體委員會審查。
API 校正
API 委員會會定期開會,進行 API 校正作業。API 校正的目的是促進專案中 API 審查的一致性,並透過跨委員會的最佳做法交叉比對,提升 API 審查品質。這類會議通常會有主持人,負責讓會議聚焦於討論主題,並確保每位參與者都有機會提供意見回饋。
Fuchsia 的貢獻者可以觀察 API 校準會議。觀看這些會議,是瞭解如何改善 API 介面的最佳做法的好方法。
查看含有 API 變更的 RFC
在某些情況下,API 變更可能需要發布 RFC 來討論所提議的變更。API 校正作業的首要任務,是審查已提交給全體委員會的 RFC。如果有多份待處理文件,主席會選定審查文件的順序。
撰寫文件的 API 設計師應提交文件,為委員會提供必要的背景資訊,以便瞭解相關問題。接著,提供文件的人員應針對他們想徵求意見的 API 設計部分,引導討論。我們鼓勵委員會成員針對這些領域提供意見,但也歡迎他們針對整份文件提供意見。
查看待處理工作量
Fuchsia API 介面包含許多在委員會成立前設計的 API。委員會將處理積壓的 API 審查作業,最終達到 Fuchsia API 途徑中每個 API 都已審查的階段。理想情況下,在 Fuchsia 承諾 API 的向下相容性之前,委員會將有機會檢查整個 Fuchsia API 途徑。
主席會選定審查待處理項目的順序,試圖平衡審查來自專案不同領域的 API,以及審查吸引大量客戶的 API 的急迫性。
審查 API 時,負責 API 所在領域的委員會成員 (以下稱為「負責成員」) 會介紹 API,並提供委員會必要的背景資訊,以便瞭解 API 的用途和動機。負責的成員可以邀請一或多位專家,協助提供其他背景資訊和技術詳細資料。理想情況下,負責的團隊成員會預先檢查 API,並列出建議的修改項目。
次要審查
委員會也會依序檢查專案的各個功能領域,針對各個區域自上次週期以來的 API 途徑變更進行二次審查。這個活動可讓委員會針對會員最近的 API 審查提供意見回饋。
主席會選取審查領域的順序,盡量平衡審查專案中不同領域的 API,並以優先審查變更量龐大的 API。
在二次審查期間,API 變更的主要審查員會在委員會中介紹變更內容,以及任何相關的 API 設計文件,讓委員會瞭解變更的用途和動機。建議 (但不強制要求) 進行相關變更的 API 設計師也一同參與。
一般來說,委員會應尊重在主要 API 審查期間做出的決定,但鼓勵委員會成員提供意見,說明 API 可以如何改善,以利日後的審查。視 API 的成熟度而定,主要審查員可能會決定將這些改善項目納入 API。在極少數情況下,審議會可根據審議會的決策程序,否決主要審查人員的決定。
特別銘謝
本文件大量參考了 Android API 委員會、Web API OWNERS、W3C 和 IETF 使用的治理架構。特別感謝 Jeff Brown、Dimitri Glazkov、Jeremy Manson、Rebecca Silberstein 和 Greg Simon,感謝他們分享 API 治理的經驗,並針對本文件的早期草稿提供深思熟慮的意見回饋。