Access to add and change pages is restricted. See: https://cwiki.apache.org/confluence/display/OFBIZ/Wiki+access

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

原始英文網頁: OFBiz Contributors Best Practices

為什麼該貢獻 OFBiz

透過改進貢獻回饋給 OFBiz, 將可獲得整個開發者與使用者社群協助除錯, 加強, 或者拓展你業務所需要的功能。此外, 假如此貢獻有利於 OFBiz, 日後會吸引更多使用者與開發者加入 OFBiz, 最終那些使用者與開發者做出貢獻的話, 又有利於你。最後, 貢獻這個專案的過程是新的使用者與開發者用來參與原有社群的方式, 並能學習更多關於 OFBiz, 發掘更多功能和彈性。

如何貢獻給 OFBiz

OFBiz 是一個社群開發的開放源碼專案。這意味著我們正在找尋使用者, 來協助我們把應用程式做得更好。任何人都可以貢獻至 OFBiz, 不必一定要成為提交者, 在審核過的名單, 或成為朋友或者有關係。所有的貢獻都被視為基於對這個專案的好處。不用提交的權限, 也可以貢獻。只要建立修補檔案, 並張貼在我們的 事例追蹤。

錯誤報告

錯誤報告是重要的且受歡迎, 即使事情不明朗, 人們還是會認真以對。問題在於 OFBiz 本身是一個大的系統, 沒有足夠細節的話, 很容易發生完全不同的結果。要讓這些清楚一點, 建議試著遵循下列方式:

  1. 做了什麼 (包含重製的細節步驟, 與網址, 欄位名稱, 確切的顯示標籤, ... 等等)
  2. 期待發生什麼
  3. 實際發生什麼 (也包括確切的錯誤訊息, ... 等等)

在這裡至少有兩種貢獻的人: 錯誤報告者, 普通貢獻者(遵守貢獻最佳實務的人)。如果沒有足夠的時間或能力解決一個錯誤, 可以直接發出報告在 使用者論壇, 但請依循上述的慣例。

如何建立一個 Jira 事例

  1. 建立一個帳號在 這裡, 如果沒有的話
  2. 登入
    1. (選擇性, 如果不確定是否為新的) 搜尋一下! 使用 "找尋事例"(Find issues) 可能找到一個已存在的事例
    2. (選擇性, 如果不確定是否為新的) 假使有相彷目標的事例, 直接在上面加上你的意見
  3. 如果事例不存在, 建立新的選用 "create new issue" 項目。事例建立的細節, 請參考 這裡
  4. 選擇 OFBiz 專案和事例型態
  5. 填妥所有欄位, 寫上你認為儘可能詳細的細節
    • 通常很重要的是在 "影響版本" (Affect Version) 欄位, 選擇所執行的 OFBiz 版本。如果執行是主力版本, 那就在環境 (Environment) 欄位指定 SVN 修改的版本。
    • 環境欄位至少載明所使用的作業系統和資料庫, 這些資料對想提供協助的人是很重要
    • 選擇相關元件(可多選)。如果所有元件都被影響, 選 ALL_COMPONENTS (罕見的情況)
  6. 如果需要帶附檔, 像修補擋, 建完事例後必須進行第二步驟。可輕鬆帶截圖到事例的範例, 參考 這裡
    • 當要帶附檔或截圖, 可增加一個意見, 在說明所在就可附加檔案。請在文字中寫明檔案名稱, 因為之後的意見有可能加入更多附檔, 全都列在一起而且距原先意見有段距離
    • 也請最好使用 .patch 做為修補檔案的附檔名。如果更新檔案檔名相同的話: Jira 能夠把之前的舊檔案轉為灰色, 不用特別去刪除他們 (有時候便於和較舊的修補檔案版本做比較)
  7. Jira 提供投票機制, 讓事例的處理更恰當 (請參考 這裡 更多的資訊)

當要建立 Jira 事例

  1. 在建立任何 Jira 事例前, 請先檢查一下, 使用相關的關鍵字詞, 確認類似的事例還沒出現過。做法是先使用 Jira 頁面右上角的快速搜尋 (Quick Search), 之後可進一步調整搜尋的資料。舉例來說, 預設會搜尋全部專案, 你應該指定搜尋 OFBiz, ... 等等。
  2. 假如要提供改進或修正的修補檔案(patch), 先建立一個 Jira 事例(如果之前沒有的話), 然後把修補檔案做成事例的附檔。
  • 如果沒有修補檔案, 但發現一個 錯誤, 趕緊建一個 Jira 事例 (如果之前沒有) 儘可能提供相關細節 (包含源碼版本, 和使用環境, 以及重製錯誤的步驟)。如果不清楚如何描述, 請參用下面樣板
    1. 做了什麼 (包含重製錯誤的步驟)
    2. 期待發生什麼
    3. 實際發生什麼 (也包括確切的錯誤訊息, ... 等等)
    4. 有的話, 提供相關網址
  1. 如果沒有修補檔案, 但想要做改良或新功能的建議, 請先在開發論壇中討論, 不要直接建 Jira 事例; 在論壇中, 社群可以充份考慮, 討論出共識後再建立一個 Jira 事例, 促進 OFBiz 未來的發展。
  2. 如果沒有修補檔案, 但計劃要做的話, 想先和社群分享設計細節, 應該使用論壇來討論而不是建立 Jira 事例; 另一方面來說, 你目前沒有時間進行, 但已經決定根據特定設計細節要做修補, 相讓社群先瞭解之後的修補檔案內容, 就可以建立 Jira 事例 (之後會把修補檔案附帶進來)。
    小結:
  • 錯誤: 任何時候發現新的錯誤, 都請建立一個新的 Jira 事例
  • 新功能/改良: 如果有修補檔案, 才建立一個新的 Jira 事例 (或是計畫很快的做出來)

修改 Jira 裡的意見

應該儘可能不用此項功能, 修改後的意見會造成論壇不易讀取和瞭解的困擾, 因為大多數人都透過開發論壇讀取意見 (Jira 事例會轉到開發論壇)。
因此應該儘可能以增加意見取代修改。如果 真的需要 修改意見, 就 必須 置放一個 明顯的前置 (加英文大寫) 在意見之前, 以便於區分原先已有的文字。應該是除了包含成雙 "*" 的加強文字或全部回覆, 要有你的名稱在其中, 以突顯增加的部份。

如果是一位經常的貢獻者, 而且可幫助此專案長遠發展的話, 就可能變成一個 專案提交者 (英)。

下面的指南主要是協助貢獻者和提交者與整個社群一同工作 :

指南

  1. 請依循 寫碼慣例 (英)。 請認真閱讀此份文件。
  2. 裝妥 OFBIZ Subversion 的 客戶端設置檔案
  3. 提交者請遵循底下兩個主要準則:
    1. 規則 #1 提交者要像醫師一樣: 首先不造成傷害. 不論在提交前或提交後, 如果會使得已有功能發生問題, 就不要進行提交。無論是和誰一起開發, 或者有人也許是很多人有機會用到它。
    2. 規則 #2 提交者要像科學家一樣: 先讀再寫. 剛開始入門, 讀和寫的時間比大約是 20:1, 當成為 OFBiz 專家通曉關於專案內外的大小事, 或許可把比例降到 3:1。
  4. 和社群討論你要的功能。說說打算實作什麼, 以及打算怎麼做? 如果你是這專案的新手, 會是很重要的事。
  5. 撰寫清楚, 良好的意見, 以及能被瞭解的程式碼。不要採取捷徑, 特別是對於變數名稱, 和錯誤或警告訊息的處理。使用能被瞭解的資料結構。請牢記, 日後有某個人會和你的程式碼相處, 讓他能好好相處。
  6. 準備一個修補檔案(patch)時, 儘可能避免在相關變更混入格式的變更 (可能的話, 把格式變更獨立出來): 這樣的話, 審核者會較容易著手處理。
  7. 準備一個修補檔案(patch)時, 請不要在程式碼加入作者資訊, 你的大名會載明在提交紀錄擋 (這是我們保存相關資訊的地方)
  8. 程式碼請使用 UI 標籤做國際化
  9. 從小規模貢獻開始, 以便於審核處理。在過程中, 藉此熟悉這個專案的程式碼風格, 以及 "思考方式"。
  10. 保持讓修補檔案和貢獻容易被審核與提交。雖然大量的程式碼很讓人感動, 但請維持事務的獨立, 以及修補檔案意圖的清晰。請瞭解到大部份的提交者可花 20 分鐘做些額外的瑣事, 但一次要費個 2 到 4 小時來做審核, 及提交一個巨大的修捕檔案就有些困難 (特別是牽涉到任何低階, 或較為敏感, 或較為複雜的東西, 這都需要投入更多的審核)。
    如果修補檔案有點複雜的話, 請提供提交者足夠的資訊以進行測試
    1. 像是實際進行的步驟, 用來測試
    2. 如果有網址(URL), 會很有幫助
  11. 把貢獻放到 JIRA, 不要直接寄給提交者, 這樣每個人都可以審核, 以及提供意見。儘管不是必要的, 但透過這種方式可讓貢獻授權給 Apache 軟體基金會, 並可被追蹤。
  12. 讓更多社群成員試用你提供的修補檔案。寫到 開發論壇 告知所完成的事情, 請大家來試看看, 並支持這項修補。這有助於提交者審核時, 對修補檔案具備更多的信心 ... 瞭解嘗試要做的目標, 也知曉它不破壞任何東西。

如果規劃進行更大的貢獻, 請按照下面的要點, 以利授權與合作的進行。這些要點讓提交者更容易審核及採納你的成果, 整體而言也利於加速你的開發過程, 要求 OFBiz 團隊進行小型且簡單的工作, 優於一整個巨大的工作, 這會讓提交者得找到時間去審核和提交。

要點

  1. 不要自行做出大型的成果(程式碼, ... 等等)之後, 才貢獻給 OFBiz。
  2. 如果有一個大型的成果要貢獻, 我們可以和你一起進行, 但和一般貢獻有差異, 必須進行不同的審核和法律撿審程序, 細節在後面網址有說明 http://incubator.apache.org/ip-clearance/index.html。
  3. 當一個方法被停用(deprecated), 需解釋該用那個方法, 及什麼被改變了。
  4. 藉由貢獻方式來替代開發。意思是如同一般的開發, 但和 OFBiz 社群透過論壇, 以及持續貢獻修補檔案保持溝通。
  5. 如果團隊中沒有一位 OFBiz 的提交者, 可能會降低開發速度, 對策是 "賣出" 一位專案中的提交者, 和 OFBiz 提交者建立結盟關係, 以持續正式審核與提交你專案中的修補檔案。請注意到, 如果讓我們知道是在擘劃進行更大進展的特質, 我們或許可找到一位志願與你一同進行工作的人。
  6. 請瞭解到在 OFBiz 中沒有支付薪水的員工, 全部都是志願者。也許會看到你的修補檔案在 Jira 待了很長一段時間, 而提交者都在處理其他事情。這通常是由於提交者會優先處理發生問題的地方, 或為了生活先去處理有付款的合約, 這才能繼續幫助 OFBiz。
  7. 沒有 OFBiz 提交者加入, 只靠自己的努力也許會有些風險。請明白提交者能在技術上, 業務上, 以及法律方面提供協助, 無論是由他們自己本身, 或透過與 ASF 內的專案成員經常性合作。

未完 ...

  • No labels