We read every piece of feedback, and take your input very seriously.
To see all available qualifiers, see our documentation.
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
我们在工作中很多时候都要做技术选型,去找寻既能满足自己需求又靠谱的第三方库;在前端开源生态季度繁盛的现状下,只要不是太小众的需求,我们很容易就能找到一堆相关的开源库,那我们具体要怎么做决策呢?我的做法是,先阅读开源库的说明文档让自己有一个感性的认识,然后挑选出其中的两三房库来进行更深入更全面的了解。如此说来,这说明文档是不是就很像我们求职时的简历呢?“简历”关都过不了,何谈“offer”啊!
本文将介绍一个库(即不局限于前端领域)所要具备的说明文档,主要包括 README.md、CHANGELOG.md、LICENSE,这些说明文档均需放置于项目的根目录。
当我们进入 GitHub 中的某一个开源代码仓库页面,除了项目信息、代码目录结构外,最先映入眼帘的就是 README.md 了,可见,其重要性不亚于 index.html 之于一个网站。
README.md 需要满足以下这些要求:
README.md
console.log('code in javascript');
一份优秀的 README.md 需要包含以下内容:
>
<script>
除了以上必须包含的内容外, README.md 中还有一些对用户友好的内容项,这些内容项往往会为你的库增色不少,所以如果可以的话,也请为你的库 README.md 加上:
CHANGELOG.md 记录了本库每个正式发布的版本,以及该版本所包含的内容。对于 GitHub 开源库来说, CHANGELOG.md 中的内容应该与 GitHub 中的 releases 保持一致。
CHANGELOG.md 具体包含以下内容:
如果你觉得维护 CHANGELOG.md 比较困难,那么其实也有工具可以从库每次的 commit message 中分析生成 CHANGELOG.md ,但这对 commit message 的规范性有一定要求,本系列后续的文章里会有详细的介绍。
LICENSE 是本库的版权声明,声明用户可以在什么范围内使用、二次看法、商用本库,具有法律效率,一般可以直接声明使用现成的协议,如 GPL / BSD / MIT/ Mozilla / Apache / LGPL 等,本文不打算介绍如何选择合适的协议,可参考《如何选择开源许可证?》。
LICENSE 对于商业项目的技术选型有这一票否定的地位,因为某些开源协议具有传染性,若你的项目使用了这样的开源库,则你的项目也必须开源,这对于商业项目来说几乎是不可接受的。
主流前端框架 React ,就曾因 LICENSE 问题,引发社区强烈不满,并遭到不少大型公司弃用,最终迫于压力下才改用最宽松的 MIT 协议,这才平息了风波。
请正确评估你所开发的库的用户群体,如果库的用户群体中包含他国人员,请为他们准备好合适语言的说明文档。而对于一个把源码托管在公共代码仓库的开源项目来说,我建议至少准备中英文两套说明文档,这将大大扩展开源库的用户群,毕竟既然辛辛苦苦做出来个开源库,总还是想多收获点 Star 和 Fork 的嘛嘿嘿~~
一般我们将默认一个说明文档是使用英语的,而把使用其它语言的说明文档的文件名上加上 IETF 语言代码,如简体中文的 IETF 语言代码是zh-CN,因此 README.md 的中文文档命名是README.zh-CN.md, CHANGELOG.md 的中文文档命名是CHANGELOG.zh-CN.md,而 LICENSE 则只需要一份英文版的就足够了。
zh-CN
README.zh-CN.md
CHANGELOG.zh-CN.md
The text was updated successfully, but these errors were encountered:
No branches or pull requests
前言
我们在工作中很多时候都要做技术选型,去找寻既能满足自己需求又靠谱的第三方库;在前端开源生态季度繁盛的现状下,只要不是太小众的需求,我们很容易就能找到一堆相关的开源库,那我们具体要怎么做决策呢?我的做法是,先阅读开源库的说明文档让自己有一个感性的认识,然后挑选出其中的两三房库来进行更深入更全面的了解。如此说来,这说明文档是不是就很像我们求职时的简历呢?“简历”关都过不了,何谈“offer”啊!
本文将介绍一个库(即不局限于前端领域)所要具备的说明文档,主要包括 README.md、CHANGELOG.md、LICENSE,这些说明文档均需放置于项目的根目录。
README.md
当我们进入 GitHub 中的某一个开源代码仓库页面,除了项目信息、代码目录结构外,最先映入眼帘的就是 README.md 了,可见,其重要性不亚于 index.html 之于一个网站。
README.md 需要满足以下这些要求:
README.md
必须包含的内容
一份优秀的 README.md 需要包含以下内容:
>
开头;尽量保持简洁且字数应少于120;与 GitHub 仓库(如果有的话)和 npm 包(同样是如果有的话)的描述保持一致。<script>
加载 CDN 资源。可选内容
除了以上必须包含的内容外, README.md 中还有一些对用户友好的内容项,这些内容项往往会为你的库增色不少,所以如果可以的话,也请为你的库 README.md 加上:
CHANGELOG.md
CHANGELOG.md 记录了本库每个正式发布的版本,以及该版本所包含的内容。对于 GitHub 开源库来说, CHANGELOG.md 中的内容应该与 GitHub 中的 releases 保持一致。
CHANGELOG.md 具体包含以下内容:
如果你觉得维护 CHANGELOG.md 比较困难,那么其实也有工具可以从库每次的 commit message 中分析生成 CHANGELOG.md ,但这对 commit message 的规范性有一定要求,本系列后续的文章里会有详细的介绍。
LICENSE
LICENSE 是本库的版权声明,声明用户可以在什么范围内使用、二次看法、商用本库,具有法律效率,一般可以直接声明使用现成的协议,如 GPL / BSD / MIT/ Mozilla / Apache / LGPL 等,本文不打算介绍如何选择合适的协议,可参考《如何选择开源许可证?》。
LICENSE 对于商业项目的技术选型有这一票否定的地位,因为某些开源协议具有传染性,若你的项目使用了这样的开源库,则你的项目也必须开源,这对于商业项目来说几乎是不可接受的。
主流前端框架 React ,就曾因 LICENSE 问题,引发社区强烈不满,并遭到不少大型公司弃用,最终迫于压力下才改用最宽松的 MIT 协议,这才平息了风波。
多语言
请正确评估你所开发的库的用户群体,如果库的用户群体中包含他国人员,请为他们准备好合适语言的说明文档。而对于一个把源码托管在公共代码仓库的开源项目来说,我建议至少准备中英文两套说明文档,这将大大扩展开源库的用户群,毕竟既然辛辛苦苦做出来个开源库,总还是想多收获点 Star 和 Fork 的嘛嘿嘿~~
一般我们将默认一个说明文档是使用英语的,而把使用其它语言的说明文档的文件名上加上 IETF 语言代码,如简体中文的 IETF 语言代码是
zh-CN
,因此 README.md 的中文文档命名是README.zh-CN.md
, CHANGELOG.md 的中文文档命名是CHANGELOG.zh-CN.md
,而 LICENSE 则只需要一份英文版的就足够了。The text was updated successfully, but these errors were encountered: