要項

原始程式碼存放庫

說明文件

參與合作

子專案

相關專案

其他

如何協助 Apache 提交修訂程式

第三方提供的修補程式對 Apache 的成功至關重要 - 這些「核心」開發人員並沒有能力存取所有平台，而且我們根本不可能以所能使用 Apache 的各種不同方式採用它。為此，我們嘗試讓程式碼的協助貢獻盡可能容易。不過，我們對協助貢獻者確實有一些期望，而且我們提供了一個流程，這樣做只是為了協助我們管理可能湧入的協助貢獻。本頁說明了這個流程。

程式碼風格

我們在程式碼中使用了一套相當穩定的程式碼格式；我們透過大量討論才達成這個格式。此格式說明在我們的官方格式指南中。雖然專案中有一些程式碼不遵循此格式指南，但如果您的程式碼格式不像檔案中的其他程式碼一樣，通常可以安全地認定您的程式碼有誤。

我們也對程式碼品質抱有非常高的期待；對我們來說，這就是避免大量的靜態緩衝區，使用記憶體池機制（確保適當的清理），以及撰寫執行序安全的程式碼。我們也希望能套用一到兩層最佳化 - 這樣使用位元遮罩會比較快嗎？index() 比 strchr() 快嗎？等等。當然，如果我們能有一份說明所有這些內容的真實文件會很好，但目前我們還沒有這個。

說明文件

必須針對某些修補程式更新 Apache 說明文件，增強程式功能時的情況尤其如此。您可能會希望確認您的修補程式是否在更新說明文件之前被視為普遍可接受。說明文件的修補程式採用與程式碼變更相同格式一併提交。

請注意，對於 Apache 2.0 及以上版本，大部分文件都是從 XML 產生的。您的變更需要在 XML 版本中做出。請參閱 https://apache-httpd.dev.org.tw/docs-project/docsformat.html 以取得更多資訊。

挑選 Apache 程式碼的對照等級

目前，有兩個活耀的 Apache httpd 原始碼樹

  1. Apache httpd 2.4.x（目前的發行版本，GA）

  2. Apache httpd 2.5.x（開發/beta 版本）

應針對最新的公開版本或適用的原始碼樹中的最新 SVN 程式碼建立一個修補程式。針對舊版本建立的修補程式可能無法套用至目前的原始碼。

從 SVN 取得原始碼樹的說明位於 Apache 開發備忘錄

修補程式格式

我們偏好以統一比對格式提交修補程式

diff -u file-old.c file.c

不過，並非所有平台都支援此格式。如果您的平台不支援統一比對，請改用脈絡比對

diff -C3 file-old.c file.c

其中 file.c 是受影響的檔案。我們應該能夠直接將修補程式提供給「patch」程式，然後讓它更新檔案或檔案組。-C3 非常重要，因為在某些程式碼檔案中行號每天可能會變動，因此具有脈絡對於了解實際插入位置至關重要。

如果會變更多個檔案，下列設定可以簡化原始檔案與已變更檔案的管理

  1. cd /sources

  2. tar xvzf httpd-2.4.x.tar.gz

  3. cp -ax httpd-2.4.x httpd-2.4.x.new

  4. 編輯 httpd-2.4.x.new 中的檔案，並進行建置/測試

  5. cd /sources

  6. diff -ru httpd-2.4.x httpd-2.4.x.new > my_unified_diff.patch

如果您的原始碼樹已從 SVN 簽出

    svn diff

將會產生正確格式的修補程式。

提交修補程式

傳統上，修補程式會在開發人員的郵件串中以及錯誤資料庫中提交。遺憾的是，這使得追蹤修補程式變得困難。而且，無法輕鬆追蹤的話，就會有太多修補程式遭到忽視。

現在，必須透過 http://bz.apache.org/bugzilla/ 中的錯誤資料庫來提交修補程式。如果您還沒有 Bugzilla 帳戶，您必須先建立一個。要提交修補程式，請先輸入新的錯誤報告。如果是 srclib/apr 或 srclib/apr-util 中的檔案的修補程式，請務必為產品指定 APR。以下資訊非常有幫助，只要有這些資訊即可

  1. 說明如何重現問題以及修補程式如何已經過測試

建置好錯誤回報後，再編輯它並指定 **PatchAvailable** 作為關鍵字，然後新增補丁作為新附件。

如果您想在開發者電子郵件清單上討論補丁，請在主旨加入「[PATCH <公關編號>]」的前綴以參照您的補丁提交。

請注意，核心開發人員對於將什麼放入 Apache 核心通常非常保守。Apache 有一個非常靈活的 API，任何進階功能都可能會被推到第三方模組。可移植性修復是最重要的；通訊協定正確性對我們來說同樣至關重要；而且我們肯定程式碼中還有更多我們想擺脫愚蠢的錯誤。這些會得到優先處理；新功能則可能不會。

如果我的補丁被忽略了怎麼辦？

因為 Apache 只有少數志工開發人員，而且這些開發人員通常都很忙碌，所以您的補丁很有可能不會收到任何立即的反饋。開發人員必須優先處理他們時間，先處理嚴重的臭蟲和程式碼中他們有興趣和知識的部分。以下是一些建議，說明您可以在補丁上採取哪些措施來鼓勵採取行動

  1. 堅持但不失禮貌。將您的補丁張貼到開發人員清單，並說明您認為它很重要的原因。您可以每週做一次，直到得到回覆。請務必保持禮貌，因為開發人員不太可能回應粗魯的訊息。

  2. 鼓勵其他 Apache 使用者檢閱並測試您的補丁，然後將註解新增到錯誤回報中。如果開發人員看到您的補丁經過廣泛測試，他們更願意檢閱並提交您的補丁。

  3. 確保您的補丁易於閱讀和套用。遵循上述各節中的所有樣式建議，並包含必要的任何文件變更。

  4. 檢閱錯誤資料庫以找出類似錯誤。如果有重複項，請將它們關閉並設為初始回報的重複項（這會參照兩個臭蟲）。關閉有充分說明的重複項時，若特定錯誤回報包含有用的獨特詳細資訊，請額外新增註解。如果有不完全相同的回報，但您的補丁可能有所幫助，請將其標示為「依賴於」包含您的補丁的錯誤回報。最後，將原始異常標示為「依賴於」有補丁的錯誤回報。

  5. 透過禮貌且正確地處理您可以介入的其他錯誤回報來賺取「額外優點」。雖然這項工作很醜陋，有點像是遊行後的清潔隊，但會讓主要的提交人有時間解決實際的 bug 及其解決方案，而不是清除掉落物。