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

原始英文網頁: 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 內的專案成員經常性合作。

實體與欄位的命名

這裡有一些慣例, 或說是樣式, 做為共通用來定義實體與其欄位。

  • 實體名稱必須是大駝峰式命名法 (UpperCamelCase)。
  • 實體名稱長度要短到以符合自動轉成的資料庫表格名稱 (大寫字母前會加上底線符號), 要小於 30 個字元。
  • 欄位名稱長度要短到以符合自動轉成的資料庫欄位名稱 (大寫字母前會加上底線符號), 要小於 30 個字元。
  • 外鍵名稱不應超過 18 個字元。
  • 如果實體名稱有縮寫像是 Unit Of Measure (UOM), 則視為英文單字處理, 如: Uom。
  • 欄位名稱必須是小駝峰式命名法 (lowerCamelCase), 且名稱應要能充份表達該欄位目的。
  • 如果關連標籤(tag)指定了兩個實體之間的關係, 則外鍵應包含兩個實體的單字, 並以底線 ("_") 區隔。
  • 如果實體關連和其它實體的定義超過一次, 就該用標題(title)屬性來區分, 定義出 "來自" 那裡或 "至" 那裡。
  • 如果兩邊欄位在 <key-map> 標籤是相同的, 就不用指定 rel-field-name。
  • 在檢視實體 (view entities) 名稱應包含所有成員實體的名稱。
  • <view-link> 應該要定義, 才能正確在網站工具(webtools)看到。

除了上面描述的之外, 也可參考 entitymodel.xsd 來瞭解標籤的用途。

停用實體

當在 OFBiz 要停用一個實體, 底下這些事情必須完成, 否則所有提交者都應駁回此修補:

  1. 將停用的實體改名, 加上 Old 在前面, 然後指定實體的表格名稱屬性, 仍舊指到資料庫原本的表格名稱。
  2. 建立新的實體取代舊的, 並寫註解做說明
  3. 實作一個服務把舊的停用實體資料搬到新的實體

將會看到這種樣式在一些地方使用。這方式是使用者所期待的, 便於從 OFBiz 的一個版本升級到另一個版本。

停用實體: 更多資訊在 這裡

如何發送貢獻 (或如何建立與使用修補檔案)

首先是為自己在 JIRA 事例追蹤服務 建立一個帳號, 然後才建立一個新的事例。描述貢獻做了什麼: 是修正一個錯誤, 改進一項既有功能, 或者建立一個新的功能? 請儘可能詳細描述, 也可能附帶螢幕截圖, 如果可以展示成果的話。OFBiz 是個巨大的專案, 對你來說很直覺的, 對其他人則不一定, 即使像是提交者熟悉這個專案也會如此。

然後送出修補檔案。這個檔案描述修改的程式碼和 OFBiz 在 Subversion 儲存庫之間的不同。請使用下面慣用名稱為修補檔案命名。
修補檔案名稱應該是 OFBIZ-編碼_功能描述.patch (OFBIZ-number_featureDescription.patch), 在這裡 OFBIZ-編碼 是 Jira 事例的名稱, 而 功能描述 是 Jira 事例的標題, 如果標題短就全放, 長的話就放部分。

可藉由以下方式建立修補檔案

  • 命令列 (請參考後面說明如何做)
  • Eclipse 內部命令 ... 不要點選 結束 (Finish), 但去做 選擇專案 (select project) 已避免在修補檔案出現首兩列文字, 參考 OFBIZ-4410 起中有意見說明此例。
  • 像是 Tortoise 這類的工具

我們偏好從根目錄建立的修補檔案, 對提交者會較容易處理合併。因此請從 OFBIZ_HOME 目錄建立你的修補檔案 (通常是 ofbiz/), 其中包含著相對的檔案路徑。
"相對的檔案路徑" 意謂修補的檔案名稱該看起來像這些:
applications/party/widget/partymgr/PartyScreens.xml
framework/webtools/config/WebtoolsErrorUiLabels.properties
不該有檔案名稱像是: C:\myfiles\ofbiz\applications\party\widget\partymgr\PartyScreens.xml

使用命令列的範例: 

svn di applications/product > OFBIZ-編號_功能說明.patch

如果有加入新的檔案, 請先使用 "add" 命令, 然後才做 diff

svn add applications/product/<我的-檔案>
svn di applications/product > OFBIZ-編號_功能說明.patch

可指定確切的檔案置入修補檔案中, 有時候有些檔案被修改過, 但不希望提交出去。舉例來說, 可以先用 

svn status applications/product

可以看到什麼檔案被改過 (那些以 "M" 開頭) 或新加的 (那些以 "?" 開頭)。
然後執行:

svn di applications/product/entity/ applications/product/script/org/ofbiz/shipment/shipment/ShipmentServices.xml > OFBIZ-編號_功能說明.patch

這個例子表示只要把 entity/ 子目錄, 以及 ShipmentServices.xml 做成修補檔案。

請確定你使用本地版本是當前最新的版本, 或儘可能是最近從 OFBiz SVN 儲存庫而來的。 本地版本可使用下面指令檢查:

svn info

要確定使用最新最近的版本, 請在動手做修補檔案前更新 SVN, 執行下面指令:

svn up

這是在提交一個修補檔案前必須要做的, 否則這修補可能無法使用。如果你的本地儲存庫是從其他 SVN 儲存庫, 像是供應商分支取出的, 而不是直接從 OFBiz 的 SVN 取得。那就應該先請上游供應商先更新分支, 合併, 而後在做 svn diff 建立修補檔案前, 更新你本地的儲存庫。

接下來上傳修補檔案到你的 JIRA 事例。請使用 .patch 為副檔名, 有些工具會使用它, 且這對提交者的工作有幫助。
最後, 同一個事例中, 如果有數個修補檔案存在, 請在意見中寫明應該使用那一個。最佳實務是更新修補檔案時, 保持相同的檔案名稱。Jira 將會特別處理, 留下這些檔案(有歷史比較好), 但因檔名相同, 舊的會變成灰色表示停用。對提交者來說, 很容易一眼看到要用的檔案。而當檔名不相同, 也能讀下面頭一個意見瞭解該怎麼做。

當 Jira 事例已完全解決, 我們會關閉事例, 而不是標示已解決。有些情況是, 雖然有暫時的方案, 但故意不 關閉 事例, 因為想獲得更多回報, 或是其他人來審核, 測試, 修正。如果是簡單的事例, 特別是本身就做好回報, 最好的方式就是逕行 關閉, 而不是之後再做 關閉。

為什麼我的修補檔案併入 OFBiz 要花那麼長的時間?

首先請記得為了要做成某件事, 某人或單位需要足夠的能力和時間來進行。在 OFBiz 裡沒有付薪水的提交者, 每個人都基於志願進行工作。這是 OFBiz 是一個社群發動專案, 自然而然的邊際效應, 和 "商業化的開源" 有所不同。

當有人提出一個修補檔案, 是要求提交者群中的某人進行一些事情, 卻是免付費的。有時候由於修補檔案太大將被忽略, 且因為有不斷的新事例, 抱怨, 問題等得處理, 可能會拉長時間(如果有的話), 之後才有機會做出回應。更遺憾的是, 沒有任何一位全職的提交者能把工作時間完全貢獻給 OFBiz, 因為沒有提交者不需要為生活奔波。大部份提交者因正職工作的關係在用 OFBiz, 由於此專案大小和複雜度的關係, 目前為止似乎是能持續貢獻 OFBiz 的唯一方式。但這並不意謂他們接受你的修補檔案能有收入, 除非你願意支付, 對他們來說會是很幸運有付費客戶, 進而達成客戶的目標。

如果你真的想要你的修補檔案被處理, 你可以這麼做。當想要它被處理, 你的工作室協助提交者處理它。可以在論壇呼籲其他人來審核, 測試你的修補檔案。這真的很重要, 因為 OFBiz 相當複雜, 很多修補檔案都違反規則 #1, 簡短來看: "首先不造成傷害"。換句話說, 是破壞別人完成已經存在的東西, 而且是其他人 正在使用 的。

有另一種選擇 ... 如同上面描述的, OFBiz 沒有資金, 且所有提交者都各自有某種形式的顧主, 通常的顧主是一群客戶。這可說明為什麼有些東西會被一直提交, 但這時候 JIRA 上修補檔案的審核和提交卻很少。如果夠幸運的話, 提交者努力的工作成果就可以回到 OFBiz 上, 這是 OFBiz 比較起來, 能有豐富功能的唯一理由, 特別是對於應用系統來說 (大部份框架相對來說都沒有贊助者)。有些人認為不公平, 也有些人認為這是很幸運的狀況, 能充份發揮並利用。

如果對你還不成的話, 請考慮更深入參與 OFBiz, 或者推動其他人參與。縱使沒有成為一位提交者, 你還是有很多方式來提供協助。這裡有成為提交者明確的列舉項目, 如果做得夠多的話。當然也可以儘管去做, 不用任何長期的承諾, 或者挑選項目進行。不用一定要成為提交者, 或是 PMC 成員才能夠做這些事情!

  1. 訂閱開發論壇, 試著讀大部份的信件, 並參與討論
  2. 審閱 Jira 裡的事例, 並發表意見
  3. 取得 Jira 裡的修補, 在本機中使用, 測試它們, 接著紀錄結果寫回意見
  4. 對於 Jira 裡的事例報告, 建立對應的修補檔案
  5. 深入瞭解 OFBiz, 並提交修補檔案以解決你發現的問題或麻煩
  6. 按照這份文件所有建議事項去做

如何讓自己成為提交者?

如果你有興趣成為提交者, 這是很棒的! 我們很高興有你的加入, 而且整個社群都會感謝你所提供的協助。

做為一名提交者, 可提供你的顧主及客戶很大的助益, 也能成為個人或職涯上很大的資產。可保證在參與活動過程中, 會獲得學習與成長。將會學習到如何建立企業應用系統, 無論是技術與商務的這兩方面。也將學習到如何和其他人協同工作, 特別是和遠方的人一起工作的方式。

更多詳細資訊以及開始進行的說明, 請參考 提交者角色與責任 頁面。

  • No labels