嗨,我是KEN。
我是世界上最好的公司-Formidable 的開源總監。
如果你以前聽說過我,可能是兩件事中的一件,或者兩者都有:
• 1、看我在推特上說一堆廢話
• 2、你瞭解開源庫,比如Slick Carousel, Webpack Dashboard, Spectacle, Cash等等……
今天我們聚焦第二點。最近(和歷史上)有很多人希望得到關於進行開源項目的指導,這也是我想寫的內容。
在我們開始討論技巧之前,我想先談談為什麼做開源項目,以及我的個人經驗。
為什麼你要寫開源軟件?
至於為什麼,有很多原因可以解釋為什麼開源對你和你的職業來說都是一件好事。
• 為你的個人品牌創造奇蹟。如果你有一個受歡迎的項目,人們就會熟悉你和你的工作
• 為你公司的品牌創造奇蹟。提供和維護一個開放源碼組合可以給品牌帶來可見的價值。給員工時間去做開源,看看他們的想法同時能讓他們明白公司是一個很好的工作場所。
• 你可以成長為一個開發者!你不只是在你的/Users/Me/devshit這些文件夾中編寫一些附加的項目腳本。而是關注這項目,保持動力去推進。
• 你的回報。就像你使用John-David Dalton放棄了lodash從而在項目上節省時間,你可以用你的代碼節省其他人的時間。你們成為了整個社區的一部分,在這個社區裡,合作和分享使大家都可以節約時間。
• 很棒的感覺。就我個人而言,每次有人感謝你的項目或者告訴你你救了他們項目的故事時,你都會有一種奇妙的感覺。
• 這可能不會給你帶來一份工作,因為大多數公司不會嚴格地基於GitHub星級來招聘員工,但如果說這對你的面試沒有幫助,那我就是個騙子。
我的經驗
換個話題。我是有史以來最差的開源維護者。好吧,也許不是最壞的,但我沒有每次都做到最好,經歷了多次失敗。但是在每一個項目中,我都從失敗中吸取了教訓,這些教訓幫助我做得更好,我將在後面介紹這些。希望讀者能從我的錯誤中吸取教訓。
簡單地寫一下我的經歷,因為與典型的開源軟件項目經驗相比,有點非傳統。信不信由你,我認為在我的整個職業生涯中,對非我自己的項目所做的貢獻可能不到20個。我整理一些東西並寫出來,我認為這些背景很重要。
我的第一個開源項目可能是我最成功的項目。我在一家公司工作,為紐約的大型時尚品牌創建電子商務網站。我是團隊的高級開發人員,通常被要求做大量的JS開發工作。和我一起回到jQuery時代…
這是有趣的是時尚電子商務系統,幾乎到處使用輪播。他們精心對系統進行復雜的、雄心勃勃的設計。現有的carousel/slider庫不夠靈活,無法支持設計目標,因此我開始從頭開始用CoffeeScript編寫carousel。它起了作用,但它肯定沒能讓我在同事中獲得任何聲望。
我看到了一個明確的需求:需要一個carousel插件,足夠靈活的支持任何設計,易於使用,易於修改。我覺得這很有幫助,為什麼不節省大家的時間,所以我將它開源……
結果證明它確實為其他人節省了很多時間,而且人們似乎喜歡它。在發佈後的頭幾個月,它的受歡迎程度達到了頂峰。我是OSS的新手,對人們真的在使用我的東西感到非常興奮,所以我會整夜不睡地快速解決問題,發佈新版本,確保沒有人能與之競爭。
最終我不再關心這個項目。我把它歸結為幾件事。首先我換了工作,所以我不再需要carousel了,對jQuery的東西不再感興趣了。但其中一個最大的原因是我已經筋疲力盡了。我太努力了。我讀了所有評論,人們都很有權利,很固執己見,人們抱怨我們不應該使用carousel。
從那以後,我在不同的場景使用一些流行的公共庫,每個庫都解決了不同的問題。我最大的恐懼之一是我再也不會寫一個流行的庫了,我的熱門作品已經被我拋在腦後了。到目前為止,我一直在逃避,有一件事一直困擾著我,那就是我覺得我用那個該死的carousel讓一半的互聯網都癱瘓了。
這是我的OSS提示,希望能幫你並且你有成功的項目,而不是用威士忌來減輕開源的負罪感。
開始
開源很像演講。許多人認為他們賣的東西不夠有價值,這是廢話。如果你讀過關於冒名頂替綜合症的文章,你會發現那篇文章是完全正確的。每個人都有自己的知識派(knowledge pie),沒有一個人擁有整個派。總有人需要你賣的東西。
我有一個明顯的優勢:a)我一點不在乎和b)有非常的自信,所以我只管把項目扔出來,但是我注意到這對很多人來說很難。我的建議:
只管去做
可能發生的最壞的情況是什麼?人們會說些廢話嗎?我有個消息要告訴你,孩子,你可以把最完美、最有用、最讓人抓狂的代碼放到GitHub上,你猜怎麼著?一定有個混蛋會進來發牢騷的。這些都是不可避免的。
最壞的情況,你會學到一些東西。有人可能會說,“嘿,這讓性能很糟糕”,你可能會說,“哦,我不擅長編程,我退出了”,或者你可能會說,“哦,謝謝你的提示,剛剛修好了,現在好多了”。這些經歷會促使你做一個能讓事情變得更好的人。
那麼你應該建造什麼呢?這就是價值百萬美元的問題!
我認為是這樣:
• 你有一個問題
• 你提供解決方案
• 您提供的解決方案非常好,以至於人們希望使用您的解決方案來解決他們的問題
所以我們來談談如何把它包裝得很好……
API設計
當你有自己的想法。你發現問題並解決了它。但是你想讓別人用對嗎?這裡有一些讓別人用你的技巧。
首先也是最重要的是,看看競爭對手和現有技術。如果別人的庫做了和你一樣的事情,你需要一些東西來區分它。假設您想構建下一個lodash。祝你好運(對不起,我得把它弄掉)。但除此之外,為了打入lodash的市場份額,你需要有一個hook,它必須更小,或者更快,或者更好的API。看到我要講什麼了嗎?
談到API設計,要考慮各個方面的平衡。例如你做了一個庫,開箱即用,但是使用者可能想要調整參數。那麼你要考慮如何實現最靈活、可配置的庫,不僅開箱即用,還要在必要時候進行配置。
除此之外,你還需要保持代碼編寫清晰、明確。
我喜歡做的一件事是用一種非常明確而不是炫耀聰明的方式來寫我的源代碼。這讓你更容易做出貢獻。明確代碼的作用是什麼,不要只有你自己知道做什麼的函數編程,要進行適當的標註和說明。
準備發佈
你解決了問題,把它包裝得很好,一切都準備好了。現在是時候發佈了。但在此之前,如果你想讓人們使用它,需要做一些事情。
寫文檔
我不是在開玩笑。你需要的是有史以來最好的文檔。避免說一些像“公正”和“簡單”這樣帶有居高臨下色彩的廢話。在文檔頂部有一個標題鏈接索引。你需要一個入門的部分,解釋如何第一次運行系統的細節。你要把API的每一個細節都記錄在文檔中。
如果有一個method,應該對預期的參數、類型和返回類型進行文檔化。完整記錄它的功能。你應該舉例說明如何使用它。讓你的庫更容易使用。
文檔中要包括如何貢獻,參與你的項目。你應該記錄如何運行所有構建的步驟。如果你引用另一個項目,或者一個概念,要創建對應鏈接。如果你引用任何可鏈接的東西,鏈接到它。
要徹底完成文檔工作,這會使你的項目有很大的不同。
寫測試
為什麼要測試:
• 它將建立你對系統健康的信心
• 將使您自信地合併PRs
• 即使你離開這個項目,系統也可以正常工作
有一次我發佈了一個庫,沒有測試,Paul Irish說,“如果它有一些測試會很酷”。我去寫測試。從這些測試中發現了15個bug !
如果你做任何事情,建議都進行測試。後期會為你節省很多時間。
Repo的先決條件
你需要準備README.md、CONTRIBUTING.md、LICENSE.txt以及一個有效、完整的package.json。
你應該始終包含README 和LICENSE.txt。
CONTRIBUTING.md不僅可以指定如何處理項目,還可以鏈接到/添加您的代碼標準。添加代碼標準,有助於參與項目和貢獻代碼。
加分項
當你寫了很棒的文檔,API很棒,所有的預發佈項目都準備好了。等等我還有一些意見。
徽章。沒有什麼比徽章更能讓你的repo看起來合法。太多的徽章看起來很爛,但如果你有一些有用的徽章,它就是合法性的標誌。它可以顯示有用的信息,諸如npm的版本,測試狀態,覆蓋率數據。
此外,Markdown支持原始HTML,因此您可以使repo頭看起來更漂亮。中間加上一句引文,讓它變得活潑一點。
還可以在這裡添加一個類似的貢獻者條目:https://github.com/kentcdodds/all貢獻者。這是一種很好的方式來認識那些為這個項目做出貢獻的人。
發佈與營銷
你怎麼能讓人們真正去查看並使用你的新庫?
我的建議非常具體。在美國東部時間星期一下午12點發行。這是Europes day的結束,紐約的午餐休息時間,以及在任何事情發生之前的舊金山早上的時間。你有很大一部分目標觀眾在互聯網上玩弄著拇指!
至於如何發佈,我認為Twitter是第一站。這個過程大概如此:
瀏覽Twitter
哦!看這個微博!
哦?這個東西做什麼! ?
點擊鏈接REPO,
哦!看起來酷!
複製/粘貼到終端,
開始搖滾吧!
根據你的粉絲數量和他們對你所推廣的任何技術偏好,你的里程可能會有所不同,但這通常是有效的。除了Twitter,還有HN(不好意思)和Reddit。
另外,如果你的想法很棒,那就在你發佈軟件的時候附上一篇博客文章,尤其以公司名義發佈,你可以用更長的文章來展示。要大膽!要自信!
維護
我很害怕進入這一段,但我很高興地告訴大家,我從失敗中學到了什麼,希望你們能讀懂。
你發佈了開源庫。它有兩種結局:
• 以失敗告終
誰在乎,我總是這樣。有時一些東西不會火, 這並不意味著你的想法錯誤。 重要的是你做了一些事情。
• 大受歡迎
如果有人對你的項目感興趣,讓他們成為一個維護者。因為新的技術會不斷出現,隨之出現很多新的問題。
接下來,我想談談與人打交道。這是一個開源的最大的問題,很多時候比編寫代碼更重要。人們會跟你說很多廢話,因為人們有權利公開地談論你的項目。
我花了很多時間為一些事情爭吵,但是並不是所有提意見的都是惡意。想想看,你面向全世界去開放項目,很多人並不使用英語。想象一下,你想為一個用俄語寫的項目做貢獻。但是你不懂俄語。所以用谷歌去翻譯“什麼時候完成?”成俄語,乍一看,俄語的意思可能會變成說:“嘿,這傢伙的問題到底是什麼”。所以,為了避免溝通的問題,建議設定一些基本規則:
• 要求複製案例或失敗的測試用例。
• 詳細描述發生錯誤的前提條件
如果你沒有時間去找出一個錯誤,那麼讓用戶向你證明這個bug的存在,並詳細描述,以便你可以花時間修復它。
特別重要的,建議你“語義化的版本控制”, 你所能做的就是讓語義化的版本控制為你提供一個健全的方式來發行以及升級套件,而無需推出新的相依套件,節省你的時間及煩惱。
結論
我希望能幫助那些想要發佈自己的開源軟件的人,併為他們節省一些時間和精力。
我還有最後一個建議。除非你真的想做,否則不要去做。不要覺得你必須這麼做。沒有它你也能找到工作。沒有它,你可以成為一個優秀的開發人員。我從中學到了很多,也很喜歡這樣做,但是我再也沒有時間去做那些我在圖書館裡做的事了,還有那些我可以和家人一起做的事,或者追求自己的愛好,或者做任何可以提供收入的事情。因為你想做就去做。如果你對你正在創造的項目沒有熱情,它可能不會成功。
原文鏈接:
https://medium.com/codezillas/a-bitter-guide-to-open-source-a8e3b6a3c1c4
譯者介紹:
楊大江,目前擔任優銘雲計算公司的培訓部門經理,職業生涯始於大學時候兼職數據庫開發,為學校開發圖書館管理系統,和參加某公司開發後端金融系統。 在IT領域工作超過20年,發表過多篇論文。參加了數個大型雲計算項目和網絡安全項目,同時在培訓和項目管理方面擁有豐富的經驗。現在也在進行區塊鏈技術的研究和項目實踐。
閱讀更多 雲技術 的文章