如何為我們的開源專案建立完美的 README?

前端小智發表於2021-11-24
作者:Rizel Scarlett
譯者:前端小智
來源:dev

有夢想,有乾貨,微信搜尋 【大遷世界】 關注這個在凌晨還在刷碗的刷碗智。

本文 GitHub https://github.com/qq449245884/xiaozhi 已收錄,有一線大廠面試完整考點、資料以及我的系列文章。

我們正在招聘,年薪:25-60萬+獎金,有興趣的可以點我瞭解詳情。

Hacktober 已經結束了,但這並不意味鼓勵程式設計師為開源做貢獻的結束。維護者吸引更多長期貢獻者的方法之一是寫一個規範的 README。這裡,參照一些流行的開源庫中的 README 整理了一份清單,讓你建立一個能吸引貢獻者加入你的社群的 README。

Hacktoberfest 是由知名雲服務商 DigitalOcean 發起的一個推廣、支援開源的年度線上活動,任何一個開源愛好者都可以參與。只要在10月份內向 GitHub 上的任意開源專案提交若干 Pull Request,就算完成活動任務,並將得到由 DigitalOcean、GitHub 等活動贊助商提供的紀念品。通常是限量版T恤、貼紙若干。

那麼,Hacktoberfest 這個奇怪的名字是什麼意思呢?這不是一個原生的英文單詞,是由幾個代表著這個活動的核心精神的單詞縮寫組合而成。其中的 Hacktober 是由 Hackathon(黑客馬拉松) 和 October(十月) fest 則是 Festival(節日)的前幾個字幕。看到這裡,大家應該就明白了吧, Hacktoberfest 就是開源愛好者在每年的十月份通過做開源貢獻的方式來傳播、慶祝開源。

我為什麼要寫 README?

就像找工作要寫個人簡歷一樣,為自己的開源專案寫一個優秀的 README 同樣重要。你README 可以為新使用者和潛在貢獻者提供了對我們專案的第一印象。說白了,你的 Contributing.md 可以讓貢獻者在你的版本庫中提出和合並拉動請求,而你的 README 則指導使用者如何使用你的專案。

我應該在 README 中寫些什麼?

首先新增專案標題

image.png

這個例子來自 Open sauce

新增一些簡短的陳述,描述專案出現原因和作用

image.png

這個例子來自Slinkity

告知使用者如何安裝和使用我們的專案

image.png

這個例子來自Timber

讓使用者知道如何獲得幫助

image.png

這個例子來自RasaHQ

包括重要文件的連結

image.png

這個例子來自CodeNameOne

展示你的貢獻者

image.png

這個例子來自 use-shopping-cart

新增專案的許可證

image.png

這個例子來自 use-shopping-cart

可以附加一點

怎麼把它弄漂亮點

試試使用Readme.so,這是由Katherine Peterson建立的開源專案,可以輕鬆建立和定製README的所有部分。

~完,我是刷碗智,勵志等退休後,要回家擺地攤的人,我們下期見!



編輯中可能存在的bug沒法實時知道,事後為了解決這些bug,花了大量的時間進行log 除錯,這邊順便給大家推薦一個好用的BUG監控工具 Fundebug

原文:https://dev.to/github/how-to-...

交流

有夢想,有乾貨,微信搜尋 【大遷世界】 關注這個在凌晨還在刷碗的刷碗智。

本文 GitHub https://github.com/qq449245884/xiaozhi 已收錄,有一線大廠面試完整考點、資料以及我的系列文章。

相關文章