原始英文網頁: OFBiz Contributors Best Practices
為什麼該貢獻 OFBiz
透過改進貢獻回饋給 OFBiz, 將可獲得整個開發者與使用者社群協助除錯, 加強, 或者拓展你業務所需要的功能。此外, 假如此貢獻有利於 OFBiz, 日後會吸引更多使用者與開發者加入 OFBiz, 最終那些使用者與開發者做出貢獻的話, 又有利於你。最後, 貢獻這個專案的過程是新的使用者與開發者用來參與原有社群的方式, 並能學習更多關於 OFBiz, 發掘更多功能和彈性。
如何貢獻給 OFBiz
OFBiz 是一個社群開發的開放源碼專案。這意味著我們正在找尋使用者, 來協助我們把應用程式做得更好。任何人都可以貢獻至 OFBiz, 不必一定要成為提交者, 在審核過的名單, 或成為朋友或者有關係。所有的貢獻都被視為基於對這個專案的好處。不用提交的權限, 也可以貢獻。只要建立修補檔案, 並張貼在我們的 事例追蹤。
Anchor | ||||
---|---|---|---|---|
|
Info | ||
---|---|---|
| ||
錯誤報告是重要的且受歡迎, 即使事情不明朗, 人們還是會認真以對。問題在於 OFBiz 本身是一個大的系統, 沒有足夠細節的話, 很容易發生完全不同的結果。要讓這些清楚一點, 建議試著遵循下列方式:
|
在這裡至少有兩種貢獻的人: 錯誤報告者, 普通貢獻者(遵守貢獻最佳實務的人)。如果沒有足夠的時間或能力解決一個錯誤, 可以直接發出報告在 使用者論壇, 但請依循上述的慣例。
Tip | ||
---|---|---|
| ||
|
Note | ||
---|---|---|
| ||
|
Info | ||
---|---|---|
| ||
應該儘可能不用此項功能, 修改後的意見會造成論壇不易讀取和瞭解的困擾, 因為大多數人都透過開發論壇讀取意見 (Jira 事例會轉到開發論壇)。 |
如果是一位經常的貢獻者, 而且可幫助此專案長遠發展的話, 就可能變成一個 專案提交者 (英)。
下面的指南主要是協助貢獻者和提交者與整個社群一同工作 :
Tip | ||
---|---|---|
| ||
|
如果規劃進行更大的貢獻, 請按照下面的要點, 以利授權與合作的進行。這些要點讓提交者更容易審核及採納你的成果, 整體而言也利於加速你的開發過程, 要求 OFBiz 團隊進行小型且簡單的工作, 優於一整個巨大的工作, 這會讓提交者得找到時間去審核和提交。
Note | ||
---|---|---|
| ||
|
Anchor | ||||
---|---|---|---|---|
|
Note | ||
---|---|---|
| ||
這裡有一些慣例, 或說是樣式, 做為共通用來定義實體與其欄位。
|
除了上面描述的之外, 也可參考 entitymodel.xsd 來瞭解標籤的用途。
Anchor | ||||
---|---|---|---|---|
|
Warning | ||
---|---|---|
| ||
當在 OFBiz 要停用一個實體, 底下這些事情必須完成, 否則所有提交者都應駁回此修補:
|
將會看到這種樣式在一些地方使用。這方式是使用者所期待的, 便於從 OFBiz 的一個版本升級到另一個版本。
Wiki Markup |
---|
{center}*停用實體: 更多資訊在 [這裡|OFBTECH:General Entity Overview#DeprecatedEntities]*{center} |
如何發送貢獻 (或如何建立與使用修補檔案)
首先是為自己在 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
使用命令列的範例:
Code Block |
---|
svn di applications/product > OFBIZ-編號_功能說明.patch |
如果有加入新的檔案, 請先使用 "add" 命令, 然後才做 diff
Code Block |
---|
svn add applications/product/<我的-檔案> svn di applications/product > OFBIZ-編號_功能說明.patch |
可指定確切的檔案置入修補檔案中, 有時候有些檔案被修改過, 但不希望提交出去。舉例來說, 可以先用
Code Block |
---|
svn status applications/product |
可以看到什麼檔案被改過 (那些以 "M" 開頭) 或新加的 (那些以 "?" 開頭)。
然後執行:
Code Block |
---|
svn di applications/product/entity/ applications/product/script/org/ofbiz/shipment/shipment/ShipmentServices.xml > OFBIZ-編號_功能說明.patch |
這個例子表示只要把 entity/ 子目錄, 以及 ShipmentServices.xml 做成修補檔案。
請確定你使用本地版本是當前最新的版本, 或儘可能是最近從 OFBiz SVN 儲存庫而來的。 本地版本可使用下面指令檢查:
Code Block |
---|
svn info |
要確定使用最新最近的版本, 請在動手做修補檔案前更新 SVN, 執行下面指令:
Code Block |
---|
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 成員才能夠做這些事情!
- 訂閱開發論壇, 試著讀大部份的信件, 並參與討論
- 審閱 Jira 裡的事例, 並發表意見
- 取得 Jira 裡的修補, 在本機中使用, 測試它們, 接著紀錄結果寫回意見
- 對於 Jira 裡的事例報告, 建立對應的修補檔案
- 深入瞭解 OFBiz, 並提交修補檔案以解決你發現的問題或麻煩
- 按照這份文件所有建議事項去做
如何讓自己成為提交者?
如果你有興趣成為提交者, 這是很棒的! 我們很高興有你的加入, 而且整個社群都會感謝你所提供的協助。
做為一名提交者, 可提供你的顧主及客戶很大的助益, 也能成為個人或職涯上很大的資產。可保證在參與活動過程中, 會獲得學習與成長。將會學習到如何建立企業應用系統, 無論是技術與商務的這兩方面。也將學習到如何和其他人協同工作, 特別是和遠方的人一起工作的方式。
更多詳細資訊以及開始進行的說明, 請參考 提交者角色與責任 頁面。