簡介: 創建一個成功的 Python 開源項目不僅僅是編寫有用的代碼。它還汲及社區參與方面,並能增加合作機會、提高技藝和增加支持。本文將探索最佳實踐,幫助您創建自己的成功項目。
Python 開源項目的生態系統豐富多樣。您可以在這一雄厚的基礎上完成下一個開源項目的生產。此外,這也意味著,有相應的一套社區規范和最佳實踐。通過遵守這些規范並在項目中應用這些實踐,可以使您的軟件獲得更廣泛的采用。
本文介紹了擁有廣泛用戶群體的大小型項目構建實踐。本文在此提供的建議合理有效。但是,結果可能有所不同,因此請不要將此建議看作是金科玉律。
首先,我們將討論解耦流程如何帶來一個更加強大的社區,在開源軟件的編寫、維護和支持方面擁有更高的生產率。
協作與合作
在 2011 年的 DjangoCon 會議上,David Eaves 發表了相關的主題演講,清楚地說明了雖然協作與合作定義相似但卻有細微的差別:
“我認為協作與合作不同,它需要項目的各參與方共同參與來解決問題。"
Eaves 還撰寫了一整篇文章,詳細介紹 GitHub 如何成為開源工作方式創新的驅動力—特別是在社區參與方面。在 "How GitHub Saved OpenSource"一文中,Eaves 表示:
“我認為,只有當參與者能夠參與到低交易成本合作中,並且最大限度地減少高交易成本合作的時候,開源項目才能發揮最大的作用。開源的精神在於它並不需要一個團隊相互協作來討論並處理每個問題,而是正好相反。”
接著,他還談論了派生 (forking) 的價值,以及如何在人群中支持低成本合作,使之能夠在無需許可的情況下推進項目,從而降低高額的協作成本。該派生可推遲對於協作的需求,直到有解決方案合並到其中,這樣能使實驗過程更為快速、更具動態。
您可以用相同的方式分享項目,並實現相似的目標:增加低成本合作,同時最大程度地減少項目編寫、維護和支持方面的昂貴協作。
編寫
從零開始,創建新的、有創意的—或與現存有所不同的東西。沒有什麼可以比得上啟動一個項目,並與全世界的人們一起分享您所努力的成果而讓人更加興奮。
與維護不同,當您進行編寫時,您是在創建新東西,而不是修改或修訂某些已存在的東西。編寫和精心創作項目是一種藝術也是一種科學。其他人將會看到這個實現,並對此代碼的質量進行評判,您的名字將永遠與這個項目聯系在一起。
因此,相應地了解工匠的思維模式以及編寫軟件的方法至關重要。編寫新項目不僅僅意味著生成代碼:項目的創作與完善包括編寫易於閱讀且樣式美觀的代碼,創建可驗證項目功能的測試,以及生成全面且有用的文檔。
技藝
工藝 通常是指手工制造並具有專業技術要求的藝術行為或職業,通常指小規模生產的物品。您可以將其定義延伸到軟件中,就此意義而言,軟件工匠關注的是軟件的質量而非數量。
對於工匠來說,重要的是,該產品不僅要功能實用,還必須吸引人。具體地講,軟件工匠要確保代碼簡潔且賞心悅目,應用程序編程界面 (API) 美觀,文檔和測試讓用戶感覺這是一種可靠的產品。
以這種思維進行工作得到的獎勵是能夠在生產開源軟件中獲得樂趣源泉:您不用理會截止日期、客戶端以及其他一些外部需求。您可以慢慢地享受創造美麗事物的過程。
為您的項目獲取一個 Twitter 帳戶,在其中人們可以公開與您討論您的。Twitter 帳號可以作為發表項目公告的一個很好的地方。
代碼樣式和 linting
Python Enhancement Proposal (PEP) 8 是關於 Python 樣式的詳細指南,您應基於此指南(或至少您項目的樣式指南)構建 Python 項目。遵守 PEP 8 教條並不是那麼重要,但是如果更接近 PEP 8,那麼對於其他 Python 開發人員以標准的 Python 社區樣式提交簡潔補丁會更加容易。
除了樣式一致性外,代碼 linting 的概念在錯誤捕捉(比如缺失導入和未定義變量)中非常有用。除了樣式檢查程序,還有許多 linter(或工具),可幫助檢查代碼以查找與默認規則集或已配置規則的偏差。最受歡迎的實用工具是:
pyflakes
pylint
pep8
不管您遵守哪一套規則,如果它們與 PEP 8 有出入,那麼我建議提供相關文檔使那些參與您項目的人了解您所使用的代碼樣式。最好是顯式表達,而不是隱式表達。
pyflakes
是一款非常有用的 linter 工具。它能很好地實現功能、捕捉與高亮顯示錯誤之間的平衡,而無需過多奇怪操作。下面是一個在 Python 項目上使用 pyflakes
的示例會話:
$ pyflakes kaleo kaleo/forms.py:1: 'form' imported but unused kaleo/forms.py:4: undefined name 'forms' kaleo/forms.py:6: undefined name 'forms'
該工具會立刻告訴我有一個輸入拼寫錯誤。查看 kaleo/forms.py,我看到:
1: from django import form 2: 3: class InviteForm(forms.Form): 4: email_address = forms.EmailField()
...告訴我將第 1 行更改為 from django import forms
。
測試
對項目進行測試以驗證代碼的運行情況總是很有幫助的,這樣可預防忽略回歸 (regressions),並在某些情況下它可作為一種文檔格式,在其中閱讀測試代碼可以告知其他人庫中的 API 工作情況。
也就是說,我不會根據項目是否包括測試或這些測試的完整程度來判斷一個項目的完整性和可行性。測試的存在並不能保證代碼的質量。這也許是一個具有爭議的觀點,但是我個人認為完全不進行測試總比測試不當要好。在編寫測試程序時,將各種輸入放置到測試中的每個單元非常重要。
文檔
但是,與測試不同,您可以 根據項目文檔的質量和范圍來判斷一個項目的質量和工藝。編寫和維護文檔的方法與您編寫和維護代碼的方法相似。文檔寫得出色並具有深度,可吸引更多的參與者加入,使用戶更接近您的項目。
使用 Sphinx 和 Read the Docs等工具,您可以擁有已發布的最新文檔,這些文檔看起來非常棒。使用這些工具與編寫詞組並按提交一樣簡單。在合適時養成盡可能使用提交鍵來提交文檔更改的習慣。
維護
發布了 Python Package Index (PyPI) 第一個版本,在各個 Tweet 和博客文章中宣布,並開始擁有一些用戶後,您就需要對所有持續活動添加維護操作。用戶將會報告 bug,請求特性,詢問在文檔中不明顯的問題等。
有些事情您可以選擇不做,並提出解決方法;但是對於其他一些事情,您可能想要在文檔或代碼中進行修改。使用 Git 等分布式版本控制系統 (DVCS) 並發布常用的開發人員軟件包,可以簡化有關維護的繁瑣工作。
源代碼控制
有多款分布式版本控制系統可用,其中包括 Git 和 Mercurial。不管您選擇哪一版本的控制系統,請確保該系統提供源代碼控制,可以讓用戶分享您的項目並自己修訂 bug。
執行更改的速度取決於許多因素,其關鍵因素之一是目標受眾(例如,其他開發人員和非技術性最終用戶)。如果您正在為開發人員編寫代碼,那麼鼓勵在 pull 請求中提供 bug 報告或特性請求可以真正地減輕維護人員的負擔。同時,它還能增強社區感,因為人們可以參與到未來發行版的構建中。
開發版本
您希望在每次發布其他補丁集後盡早且頻繁地多次發布開發版本。這樣可以使其他在工作中使用您項目的開發人員更加輕松地運行項目的最新更改。在不同場景中使用代碼的人越來越多,在發布新穩定版本時質量就越好。
支持
維護隨之而來的是支持。參與並構建一個由用戶和參與者組成的社區至關重要。授權其他人幫助您提供支持,可提高項目的總體合作因素,使項目規模獲得更好的擴展性並自然地加強解決用戶問題的觀點。
因此,確保提供多個通道以提高普及率並使用戶能夠更加輕松地參與您以及項目。通道選項包括 IRC、郵件列表和社交媒體(比如 Twitter)。
IRC
在 freenode 等 IRC 上建立通道是一個好想法。我就為自己的項目 nashvegas 建立了這樣一個通道;雖然除了我沒有別的用戶,但是我的 IRC 客戶端能在後台運行。當臨時用戶有問題時,我能夠以很低的事務處理成本且更加動態的方式來回應此問題,而不是通過電子郵件。
郵件列表
大多數開源項目均支持郵件列表並且在參與者之間討論開發流程,這是一種標准實踐。我推薦將它保存到一個郵件列表中,並且在人員數量不斷增加而導致麻煩時將其列表分成“用戶”和“開發人員”列表。
為您的項目獲取一個 Twitter 帳戶,在其中人們可以公開與您討論您的作品。Twitter 帳戶也可以作為發布項目公告的一個好地方。
結束語
在 Python 社區中編寫和參與開源軟件也非常有趣。本文側��於降低高成本協作,同時提高低成本合作機遇,可幫助您的項目與活動參與者一起成長。在開源中,當提到自己的 項目時,您有成為一名工匠的自由:充分利用它並享受其中。關注一致的代碼樣式、可靠的測試和編寫良好的文檔,以提高用戶和其他開發人員采用您項目的比率。 此外,請使用 DVCS,留意 pull 請求並發布常用的開發版本。最後,您可以通過提供多通道支持並充許社區幫助提供支持,從而進一步提高您項目的采用率和增長率。