基本原理

原始程式庫

文件

參與

子專案

相關專案

雜項

準則

這份文件定義了 Apache HTTP 伺服器專案 的準則,包括衝突解決方式(投票)、誰有資格投票以及針對 Apache 產品提出和進行變更所須遵循的程序。

我們的目標是在不必要的變更衝突的情況下,持續適時地生產出高品質的系統。也許無法避免所有衝突,但是至少我們可以針對衝突解決程序取得共識。

人物、地點和事物

Apache HTTP 伺服器專案管理委員會

負責管理 Apache HTTP 伺服器專案的志工小組。這包括決定哪些部分要作為 Apache HTTP 伺服器專案的產品進行散佈,維護專案的共用資源,代表專案發言,針對 Apache 產品的授權爭議進行調解,提名新的 PMC 成員或提交者,並制定這些準則。申請加入 Apache PMC 必須經過邀請,且必須經由現任 Apache PMC 成員共識同意。一位 PMC 成員若自行宣告離開,或是在六個月內沒有以任何形式為專案做出貢獻,將會被視為不活躍成員。不活躍的成員只要改變讓自己成為不活躍的原因(也就是說,收回自己的聲明或重新為專案做出貢獻),即可再次成為活躍成員。會員資格若要被撤銷,必須經過除了當事成員以外的所有活躍 PMC 成員一致投票同意。

Apache HTTP 伺服器提交者

一群負責 Apache HTTP 伺服器專案技術層面的志工。這個小組有適當的程式庫寫入權限,且這些志工可以在任何技術討論中進行具有約束力的表決。成為提交者的會籍名單僅限邀請制,而且必須經活躍的 Apache PMC 成員共識後才能核准。提交者經由他/她自行宣佈或在超過六個月內未以任何形式對專案有所貢獻,就會被視為非活躍狀態。非活躍的成員可以透過扭轉使得他/她成為非活躍狀態的任何條件(,扭轉他/她先前的宣佈或再次對專案的工作有所貢獻)而再次成為活躍狀態。會籍資格可以透過所有活躍 PMC 成員(除了正在討論的是 PMC 成員的話)的一致表決而被撤銷。

Apache 開發人員

所有志工對 Apache 專案貢獻時間、程式碼、文件或資源。持續向專案貢獻歡迎的內容超過六個月的開發人員通常會被邀請成為提交者,儘管此類邀請的確切時機取決於許多因素。

郵件清單

Apache 開發人員主要的郵件清單,用於討論與專案相關的問題和變更(dev@httpd.apache.org)。任何人都可以訂閱此清單,但只有訂閱者可以對清單直接發文。

私人清單

Apache PMC 的私人郵件清單,用於討論不適合公開討論的問題,例如法律、個人或安全問題(在發佈修正前)。只有 Apache httpd 的專案管理委員會被允許訂閱此清單(事實上:強制訂閱)。

Subversion

所有 Apache 產品都使用Subversion維護在共用的資訊儲存庫中。僅有部分 Apache 開發人員擁有這些儲存庫的寫入權限;每個人都擁有讀取權限

狀態

每個 Apache 專案的活躍原始碼儲存庫包含一個名為「STATUS」的文件,用於追蹤儲存庫內的議程和工作計畫。「STATUS」文件包含有關發行計畫的資訊、自上次發行以來已提交程式碼變更的摘要、正在討論的建議變更清單、個別開發人員正在處理或希望進行討論的項目簡介,以及任何可能對小組追蹤進度有幫助的其他資訊。活躍的「STATUS」文件會在每週自動張貼至郵件清單中。

專案會遇到許多問題,每一個問題都會導致零個或更多個建議的動作事項。問題應該在發現後儘快在電子郵件列表中提出。動作事項必須在電子郵件列表中提出,並加到相關的狀態檔案。所有動作事項都可能進行投票,但並非所有動作事項都需要進行正式投票。

投票

任何 Apache 開發人員都可以對任何問題或動作事項進行投票。但是,只有 Apache 伺服器專案的活躍成員所投的票具有約束力,如果投票涉及源碼或文件的變更,則變更項目的主要作者也可以對該問題投出具有約束力的票。所有其他投票都不具有約束力。鼓勵所有開發人員參與決策,但是最終決策是由那些長期為專案做出貢獻的人做出的。換句話說,Apache httpd 專案是一種最低門檻的精英制度。

投票行為會帶來一定的義務 -- 投票成員不僅表明他們的意見,還同意幫助執行 Apache 專案的工作。由於我們都是志工,因此成員們經常會因需要處理他們的「真正工作」或投入更多時間到其他專案而處於非活躍狀態。因此,整個小組成員對每一個問題進行投票的可能性很低。為了解決這個問題,所有投票決策都基於最低法定人數。

每一票有三種味道

需要共識通過的動作事項必須至少收到3 票具有約束力的+1 票,並且沒有否決票。需要多數通過的動作事項必須至少收到 3 票具有約束力的+1 票,並且+1 的票數多於-1 票(,多數票,最低法定人數為 3 票肯定票)。除非有人投了-1 票,否則所有其他動作事項都視為懶惰通過,此後將根據動作事項的類型由共識或多數投票來決定。

投票會計會在 STATUS 檔案中,並鄰近於待投票的行動項目。所有投票都必須傳送到郵件清單或直接新增到該行動項目的 STATUS 檔案項目中。

行動項目類型

長期計畫

長期計畫只會宣布群組成員正處理與 Apache 軟體相關的特定問題。這些不會投票,但不同意特定計畫或認為另類的計畫會更好的群組成員有義務告訴群組他們的想法。一般來說,在花時間在較不適當的解決方案之前,優先聽聽另類的計畫總是比較好。

短期計畫

短期計畫是宣布開發人員正處理特定文件集或程式碼檔案,其含義為,其他開發人員應避開這些或嘗試協調整合他們的變更。這是一個主動避開衝突和重複作業的好方法。

發行計畫

一個發行計畫可以用來讓所有開發人員知道何時需要發行版本、版本管理者會是誰、何時凍結儲存庫以建立新版本,以及各種各樣的瑣事,以避免我們在最後一刻措手不及。懶惰多數(至少 3 x +1 及比 -1 多的 +1)會決定發行計畫中的每個問題。

發行版本測試

在建置好一個新發行版本之後,俗稱為 tarball,必須在釋出給公眾前測試。tarball 才能公開釋出。

重大錯誤

重大錯誤是在下一個公開發行版本之前需要修好的問題。它們會列在 STATUS 檔案中,以便將特別注意集中在問題上。問題會在 STATUS 中列為重大錯誤,並由懶惰共識維持此狀態。

產品變更

Apache 產品的變更,包括程式碼和文件,會以符合變更狀態的數個類別顯示為行動項目

變更提交時機

想法必須先審查再提交;更新檔可以先提交再審查。透過提交再審查的程序,我們相信執行提交的開發人員對於變更具備高度的信心。在提交至儲存庫前,需要討論有疑慮的變更、新功能和大規模的全面檢討。會影響可設定指令設定值語義的任何變更、大幅增加程式執行時期大小或變更既有 API 函式語義,都必須在提交前獲得郵寄清單的共識核准。

每位開發人員負責在提出產品新功能或重大變更想法後通知郵寄清單,並在狀態中新增行動項目。Apache 專案的散佈式性質需要 48 小時的事前通知才能適當地審查重大變更--在變更提交前,必須對概念或特定更新檔的共識核准。請注意,成員可能會否決這個概念 (並提出充分的說明),但如果特定更新檔解決其異議,則稍後會撤銷否決。提交單獨的錯誤修正不需要事前通知。

相關的變更應該群組提交或盡量接近一起提交。半完成的專案不應提交,除非這樣做有其必要以便將重任交棒給已同意在短時間內完成專案的另一位開發人員。在提交所有程式碼變更前,這些變更必須在開發人員的平台上順利編譯。

目前原始碼樹應該在任何時候都能完全編譯。不過,有時某個平台的開發人員在變更提交後無法避免損毀其他平台,特別是在完成變更時需要存取其他平台上的特殊開發工具時。如果預期某個變更會損毀其他平台,提交者必須在提交記錄中註明這件事。

提交者負責提交至儲存庫的任何協力廠商程式碼或文件的品質。所有提交至儲存庫的軟體都必須受 Apache LICENSE 承保,或含有版權和許可,才能在與 Apache LICENSE 相同的條件下重新分發。

如果投票成員之一否決了提交的變更,且否決條件無法立刻由「修正錯誤」提交相符時,必須撤銷否決。在任何公開版本包含變更之前,必須撤銷否決。

CHANGES 檔案和 Subversion 記錄檔

變更記錄

許多變更應標示在 CHANGES 檔案中,且所有變更都應記載在 Subversion 提交訊息中。通常 Subversion 記錄檔文字和 CHANGES 項目是相同的,但不同的需求有時會產生不同的資訊。

Subversion 記錄檔

Subversion 提交記錄檔訊息包含任何資訊,由下列人員需要

如果變更程式碼是由非提交者提供的,請使用 Submitted-by 屬性。如果按原文提交變更,請找出檢閱該變更的提交者,並使用 Reviewed-by。如果變更以修改方式提交,請使用適當用詞記錄這一點,如果進行提交的人進行了變更,可以使用「已提交變更」;如果其他人對提交的程式碼有貢獻,可以使用「已提交 xxxx 的貢獻」。

範本記錄檔訊息

檢查解析內容長度的回傳碼,以避免在要求包含無效內容長度時發生當機。

PR:99999

提交者:Jane Doe <janedoe example.com>

檢閱者:susiecommitter

在例行更新 STATUS 時,如果要提出後續版本或進行投票,提交資訊可以少一點。

CHANGES

CHANGES 是從一個版本升級到下一個版本時,最終使用者需要看到的資訊子集

對於少數個人有用或不涉及評估新版本資訊的 CHANGES 使用性會下降。具體來說

更動適用於 alpha 發行版之間的更動,因此將更動從 trunk 回溯移植到穩定版本通常不需要從 trunk 中的 CHANGES 檔移除更動。

更動的歸屬是負責程式碼更動的任何人。

格式設定

識別非提交者姓名,以及他們匿名的電子信箱(如有)。匿名處理是將「@」替換為空白,並在地址前後新增「<」及「>」。例如,將 user@example.com 變更為 <user example.com>

識別提交者的 Apache 使用者 ID,例如 xyz(不需要網域名稱)。

如果更動與 Bugzilla 問題相關,請以下列格式將公關編號包含在日誌中

   PR 1234

與安全相關的更動應從這裡開始

    *) SECURITY: CVE-YYYY-NNNN (cve.mitre.org)
       xxxxx

大多數更動都插入在 CHANGES 檔的最上方。但是,與安全相關的更動應始終置於相關發行版更動清單的最上方,因此如果檔的最上方有未釋出的安全更動,請在它們下方插入其他更動。

範例 CHANGES 項目

    *) SECURITY: CVE-2009-3095 (cve.mitre.org)
       mod_proxy_ftp: sanity check authn credentials.
       [Stefan Fritsch &lt;sf fritsch.de&gt;, Joe Orton]

    *) SECURITY: CVE-2016-1546 (cve.mitre.org)     
       mod_http2: restricting number of concurrent stream workers per connection if client is slow.

提交安全修正

開放原始碼專案(ASF 或其他)在提交漏洞修正時,具有不同的程序。這些程序的一個重點,是修正漏洞時是否能在包含提交日誌且可能含有 CHANGES 項目的儲存庫中進行提交,這些提交有意模糊漏洞,並省略任何可用的漏洞追蹤資訊。Apache HTTP Server 專案已決定,最符合使用者利益的做法,就是盡可能提供此類程式碼更動之初次提交的說明,以及任何可用的追蹤資訊(例如 CVE 編號)。修正的提交將會延遲,直到專案確定所有有關問題的資訊都能共享為止。

在某些情況下,即使無法取得問題的完整資訊,但提早分享程式碼,包括更廣泛的檢閱、測試和修正的發行等可能性,也能帶來非常實際的益處。不過,只分享程式碼更動而會讓熟練的分析師能確認影響和利用機制,但一般使用者社群卻無法確定是否應採取預防措施之疑慮,遠大於這些益處。

如果在確定錯誤可被利用之前,先行提交修正而使漏洞部分揭露,httpd 安全團隊將個案審查決定要在何時記錄安全影響和追蹤編號。

修補程式格式

修補程式

當軟體的特定變更建議在郵件清單上面討論或表決時,應以 patch 命令輸入的形式呈現。寄送至郵件清單時,訊息應包含開頭為 [PATCH] 的主題以及與該 patch 的動作項目相對應的一行摘要。在其後,應更新 STATUS 檔案中的 patch 摘要,以指向該訊息的 Message-ID。

應使用 diff -u 指令,從原有的軟體檔案到修改後的軟體檔案來建立 patch。例如:

應將解決某項動作項目所需的所有 patch,串聯在單一的 patch 訊息中。如果 patch 在後續需要修改,應張貼整個新的 patch,而不要只張貼兩個 patch 之間的差異。然後應更新 STATUS 檔案中的項目,以指向新的 patch 訊息。

當在目標儲存庫中執行下列命令時,完成的 patchfile 不應產生錯誤或提示:patch -s < patchfile

附錄

本文檔中未完成的事項