README 模板

项目使命

这里应该包含一个关于你的项目使命的简短描述(3-5句话)。其目的是说明项目打算做什么,并帮助外部的贡献者大致了解项目的哪些类型的功能可能会受到欢迎。

参见《生产开源软件》中的使命宣言篇

快速入门

这一部分应该包含为第一次使用的用户编写的关于如何开始使用这个项目的简短文档。其它的详细信息文档可以通过链接的方式加入这个小节。

更多信息

这一部分可以列出以下任何或全部内容。

  • 软件所涉及的功能、用例的清单。

  • 用于解决权衡问题的设计原则的信息

  • 用户级文档的链接

  • 常见问题(FAQ)的答案,最好是可以链接到具体问题及其答案的格式,以方便参考。

获取帮助

这一部分应该包含一个简短的文档,让用户了解如何获得项目的帮助。 文档可以很简单,如果你的项目想要回答问题的话,可以把用户指向问题追踪链接。 它也可以指向一个存档和可搜索的聊天频道,或者存档的可搜索邮件列表,或者在线用户论坛。

参与项目

这一部分应该包括如何与该项目取得联系的信息。通常,这将包含存档的、可搜索的和可链接的沟通渠道的链接。

关于我们

这是一个给项目的 Trusted Committer 以荣誉的好地方。

这里可以包括作为一个 Trusted Committer 人对这个项目意味着什么的信息--尽管理想情况下, 一个组织中的所有项目都使用相同的定义,而这里提供的只是指向这个定义的链接。在这里保留链接的原因是为了让那些没有或很少 在内源项目中工作和贡献经验的同事能够直接从他们日常工作中需要的技术项目链接中获取到公司范围内的信息。

贡献指南

这一部分应该记录(或链接到文档)所有第一次贡献者需要知道的事情,以便更好开展工作。通常情况下,文档中不会包含下面的所有主题。 文档描述的重点是你的项目中与标准设置不同的地方,以及以前的贡献者认为难以理解的地方。

  • 如何获取源代码。

  • 如何找到你的项目需要帮助的问题清单--这些问题既可以是技术性的,也可以是非技术性的。一般来说,你会把这些问题放在问题跟踪器中,供贡献者访问。

  • 链接到更多的文件,例如关于项目的结构、一般的编码风格、测试惯例......。

  • 对于技术贡献。进行代码修改,构建项目并测试你的修改。

  • 将你的修改提交给项目。

理想情况下,你还应该包括关于项目的首选开发流程的信息。贡献者应该先打开一个issue并提交修改提案,还是欢迎他们立即提交修改? 在检视贡献时,什么对你来说是重要的?

此外,你应该概述你希望在项目中遵循的任何设计原则。将这些原则明确化往往有助于更快、更容易地解决权衡问题解决方案。 此外,它还有助于使原本隐含的假设变得透明。

随着时间的推移,你会注意到这一节会有很大的增长。在这种情况下,可以考虑将这些信息转移到不同的文件中,例如,CONTRIBUTING.mdTESTING.md

Last updated