開源最前線(ID:OpenSourceTop) 猿妹綜合整理
項目地址:https://github.com/RichardLitt/standard-readme
很多開發者在Github上創建一個項目的時候,往往忽視了Readme的重要性,實際上,Readme文件通常是你開源項目的第一個入口點,它的作用主要有告訴人們為什麼應該使用你的項目,以及如何安裝和使用,一份標準化的Readme可以簡化它的創建和維護,所以Readme值得你花時間去創建。
今天,猿妹和大家分享一個教科書般的Readme——standard-readme,目前該項目在Github上已經標星2.3K,605個Fork。(Github地址:https://github.com/RichardLitt/standard-readme)
這個庫包含:
- 定義標準的Readme規範
- 應該有一個linter來維護Readme
- 創建標準readme的生成器
- Badge
- 標準Readme中的示例
標準Readme是為開源庫設計的。儘管它以前用於Node和npm項目,但它也適用於其他語言的庫和包管理器。
背景
項目背景就是你為什麼做這個項目,動機和背景是什麼。當其他開發者無需查看模塊代碼就可以使用你的項目時,你的文檔即已完成,這意味著你可以將模塊的文檔化接口與內部實現分開,所以只要接口保持不變,你就可以自由更改模塊內部代碼。
安裝
該項目需要你安裝node和npm,如下:
$ npm install --global standard-readme-spec
Generator
使用Generator,請查看generator-standard-readme。該程序包中有一個全局可執行文件來運行生成器,別名為standard-readme。(Github地址:https://github.com/RichardLitt/generator-standard-readme)
Badge
如果你的Readme符合標準要求,並且你使用的是Github,那麼使用Badge就會很有用,如果要以Markdown格式添加,請使用以下代碼:
[![standard-readme compliant](https://img.shields.io/badge/readme%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme)
維護者
你可以直接@該項目相關的維護者,這樣其他人也可以輕易聯繫到他
貢獻者
創建一個項目不容易,最後還是要感謝一下所有的貢獻者。
License
最後的最後你需要聲明項目的開源協議,不同的開源協議的限制條件是不一樣的,這就需要你自己查閱相關條款,選擇一個最適合自己項目的開源協議。
閱讀更多 程序員BUG 的文章