Noob Docs

必须采用潜在用户可以理解的语言（例如，它使用最少的术语/行话）。

除非另有说明，否则我们假定 GitHub上的项目使用问题列表（Issues）和拉（Pull）请求。这些信息可以简短，例如，说明项目使用拉请求，问题跟踪器或邮寄到邮件列表中的哪一个。

FLOSS是以符合开源定义或免费软件定义。此类许可证的示例包括 CC0 ， MIT ， BSD 2条款， BSD 3条款修订版， Apache 2.0 ， Lesser GNU通用公共许可证（LGPL），以及 GNU通用公共许可证（GPL）。为了我们的目的，这意味着许可证必须是：

• 开放源码促进会（OSI）批准的许可证，或
• 自由软件基金会（FSF）批准的免费许可证，或
• Debian 主流可接受的免费许可，或
• a "good" license according to Fedora。

该软件也可以用其他许可证（例如，“GPLv2或专有”是可以接受的）。

OSI （开放源代码促进会）使用严格的审批流程来确定哪些许可证是开源软件（OSS）。

一种约定是将许可证发布为名为LICENSE或COPYING的顶级文件，其后可以带有扩展名，例如“ .txt”或“ .md”。另一种约定是使用一个名为LICENSES的目录，其中包含许可证文件。这些文件通常被命名为其SPDX许可证标识符，后跟适当的文件扩展名，如REUSE Specification中所述。请注意，此标准只是源存储库上的要求。从源代码生成某些内容（例如可执行文件，程序包或容器）时，无需包括许可证文件。例如，在为综合R存档网络（CRAN）生成R软件包时，请遵循标准CRAN惯例：如果许可证是标准许可证，请使用标准简短许可证规范（以避免安装另一文本副本）并列出排除文件（例如.Rbuildignore）中的LICENSE文件。同样，在创建Debian软件包时，您可以在版权文件中放置一个指向/ usr / share / common-licenses中的许可证文本的链接，并从创建的软件包中排除许可证文件（例如，通过在调用dh_auto_install之后删除文件） ）。我们鼓励在可行的情况下以生成的格式包含机器可读的许可证信息。

该文档必须在某些媒体（例如文本或视频）中，包括：如何安装它，如何启动它，如何使用它（可能使用教程使用示例）以及如何安全地使用它（例如，做什么和不做什么），如果这是软件的一个适当的话题。安全文档不需要太长篇幅。项目可以使用非项目内容的超文本链接作为文档。如果项目不生产软件，请选择“不适用”（N/A）。

外部接口的文档向最终用户或开发人员解释如何使用它。这将包括其应用程序接口（API），如果软件有。如果它是一个库，记录可以调用的主要类/类型和方法/函数。如果是Web应用程序，定义其URL接口（通常是其REST接口）。如果是命令行界面，请记录其支持的参数和选项。在许多情况下，最好是自动生成大部分文档，以便本文档随着软件的更改而保持同步，但这并不是必需的。项目可以使用非项目材料的超文本链接作为文档。文档可以自动生成（实际上这通常是最好的方法）。可以使用Swagger / OpenAPI生成REST接口的文档。代码界面文档可以使用 JSDoc （JavaScript）， ESDoc （JavaScript），pydoc（Python）和Doxygen（很多）。仅在实现代码中添加注释不足以满足本条款；在没有阅读所有源代码的情况下，需要一个简单的方法来查看信息。如果项目不生产软件，请选择“不适用”（N/A）。

您可以从Let's Encrypt获取免费证书。项目可以使用（例如） GitHub页面实现此条款， GitLab页面，或 SourceForge项目页面。如果您使用具有自定义域的GitHub页面，则可以使用内容传送网络（CDN）作为代理来支持HTTPS，例如博客文章“使用CloudFlare安全加速GitHub页面”，以满足此条款。如果您支持HTTP，我们敦促您将HTTP流量重定向到HTTPS。

可接受机制的示例包括归档邮件列表，GitHub问题和拉请求讨论，Bugzilla，Mantis和Trac。如果满足这些标准，异步讨论机制（如IRC）是可以接受的；确保有一个URL可访问归档机制。允许专有JavaScript，但不鼓励。

英语是计算机技术的通用语言；支持英语增加了全球不同潜在开发者和检视者的数量。即使核心开发人员的主要语言不是英文，项目也可以达到这个标准。

至少，项目应尝试响应重大问题和漏洞报告。可能正在维护一个积极追求徽章的项目。所有项目和人员的资源都有限，典型项目必须拒绝某些提议的更改，因此有限的资源和提议拒绝本身并不表示未维护的项目。

当项目知道将不再维护该项目时，应将此标准设置为“未满足”，并使用适当的机制向其他人指示该项目将不会得到维护。例如，使用“ DEPRECATED”作为其自述文件的第一个标题，在其主页开头附近添加“ DEPRECATED”，在其代码存储库项目说明的开头添加“ DEPRECATED”，在其中添加无需维护的标志其自述文件和/或主页，在任何软件包存储库中将其标记为已弃用（例如npm deprecate ），和/或使用代码存储库的标记系统对其进行归档（例如GitHub的“ archive”设置，GitLab的“ archived”标记， Gerrit的“只读”状态，或SourceForge的“已放弃”项目状态）。可以在这里找到更多讨论。