它是什么
许多人和组织在可用性、开发(无论是否计划进一步开发)和支持(无论是否提供错误修复和用户帮助)的不同状态下都有公开可用的代码。随着代码共享网站(如GitHub、Gitorious等)越来越受欢迎,新项目从第一次提交时就开始公开共享,项目在开发和支持停止后很长一段时间内继续公开访问,这种情况变得越来越普遍。到目前为止,似乎很少有方法可以让作者/维护人员指示项目的可用性和开发/支持状态。最好是标记和发布(即使在使用塞姆弗正确地说)只区分作者认为是生产就绪的代码和预发布的代码(甚至预发布状态的定义也有很大差异)。没有公认的方式表明项目的开发或支持状态,特别是是否计划进一步开发以及是否将提供支持。Repostatus.org旨在通过提供一种易于使用的方法来向人类和机器传达项目的可用性和开发/支持状态,从而填补这一空白。
这可以通过在项目的README文件中包含一个简单的徽章或URL来实现,或者通过在项目中的特殊命名文件中包含链接来实现。人类很容易看到徽章,机器可以通过在一组可能的文件列表中搜索与特定模式匹配的字符串来确定项目的状态。我们定义了一个可能的项目状态列表,旨在以简单和以用户为中心的方式包含代码完成和开发/支持状态(未来计划)的轴。
项目状态
- 概念–还没有实现或实现得很少,或者存储库只是一个有限的示例、演示或概念验证。
- WIP(在制品)–初始开发正在进行中,但还没有适合公众的稳定可用版本。
- 已暂停–初始开发已经开始,但还没有稳定可用的版本;工作暂时停止,但作者打算继续工作。
- 被遗弃的–初始开发已经开始,但还没有稳定可用的版本;该项目已被放弃,作者不打算继续开发。
- 活动–项目已达到稳定、可用状态,正在积极开发中。
- 非活动–项目已达到稳定可用状态,但不再积极开发;如时间允许,将提供支持/维护。
- 不受支持–项目已达到稳定、可用的状态,但作者已停止对其进行所有工作。可能需要新的维护人员。
- 已移动-项目已移至新位置,该位置的版本应被视为权威。此状态应附带一个新的URL。
这些状态描述和相应图标的URL也可在JSON文件或者在更正式的本体中使用SKOS公司,在中定义JSON-LD文件.
它看起来像什么
当使用推荐的方法(嵌入在项目的README文件中的徽章)时,它与下图一样简洁:
这包括三个部分:
- 图像URL,用作机器可读的状态标识符。它指向存放在repostatus.org上的特定于状态的图像,还包含了规范版本号。
- 图像上的Alt-text(通常可以通过将鼠标悬停在图像上在浏览器中查看),以规范项目状态(“项目状态:“),然后可以选择由项目维护人员提供的可读状态描述。这样的文本出现在徽章后面可能也很有用。
- 该图像链接回repostatus.org上的特定状态描述。
如何使用
将项目设置为使用RepoStatus.org非常简单,只需将适当的徽章添加到项目的README文件中即可。我们将此文件定义为项目顶层的任何文件,其名称以(区分大小写)字符串“readme”开头。当程序检查项目状态时,它们将搜索/^自述文件.*$/i
文件,并选择其中包含有效repostatus.org状态URL的第一个文件。如果这不适合您的项目,还可以使用下面描述的一些其他选项(“仅机器可读”)。请注意,虽然我试图认为这是尽可能灵活的,但强烈建议将徽章显示在项目站点上呈现的README文件中(例如GitHub存储库中的自述文件呈现)。
下面是各种状态图标,以及可粘贴的标记,以各种标记语言添加它们。可以随意更改alt-text(在第一个-
)以满足您的需求。
机器只读
如果出于某种原因,您不想让人们看到repostatus.org状态标识符(这违背了这个想法的一半目的,但可能对某些人有效),您可以将状态图像的URL放在.repostatus.org
或repostatus.org网站
文件位于项目的顶层。根据规范,确定项目状态的程序检查这些文件之后README文件。
规范
我真的想为此编写一个完整的规范,包括描述不同状态的版本化URL和JSON元数据。如果世界上还有其他人想使用这个东西,也许我会这么做。同时,这里是“规范”的当前版本。
要在链接的开放数据上下文中使用repostatus.org词汇表,请参阅JSON-LD文件.
标识符字符串
repstatus.org徽章URL是状态的权威标识符。无论其他格式如何,当机器尝试确定状态时,只应键入URL匹配/^网址:\/\/*repostatus\.org\/bodes\/(.+)\/(.+)\.svg$/
。第一个捕获组标识规范/API版本,第二个捕获组识别状态名称。请注意,规范/API版本当前可以是塞姆弗-兼容字符串或字符串“最新”。
移动的标识符字符串
“已移动”状态稍微复杂一些,因为它还必须指定新位置。使用指南如下:
- 如果链接嵌入到支持图像的alt-text(即ReST、Markdown或HTML)的标记格式中,则alt-text必须以字符串“项目状态:已移动到“其中````是新的URL(项目移动到的位置)。该字符串__should__后面跟一个连字符,然后是官方状态描述。图像__must__仍然链接到相应的repostatus.org URL。图像标记__may__后面可能会有指向新URL的单独链接。
- 标记格式不支持图像的alt-text(即纯文本文件)必须以格式指定此状态“到".
- 如果还不存在新的URL,那么存储库的状态应该是“已放弃”,而不是“已移动”。
任何对“已移动”状态的机器解析都应该递归地遵循repostatus.org标识符,以确定项目的最终位置。
机器位置和分析
机器解析非常简单:首先,搜索项目顶级目录(理想情况下在默认分支上,通常是git的master)中匹配的所有文件/^自述文件*$/i
(注意区分大小写)按字典顺序排列。第一个与标识符字符串(URL)匹配的人获胜,文件中第一个完全匹配的人也获胜。如果没有匹配的文件,则搜索.repostatus.org
文件,如果找不到任何文件repostatus.org网站
文件。计算机解析应该遵循完整的规范,而不是假定文件名(或假定项目的自述文件将正确显示在GitHub上)。
上列出了一些示例解析器解析程序第页。
变更日志
请参阅GitHub上的CHANGELOG.md.
贡献
这是我的一个疯狂想法。但我认为它很有用。我非常乐于接受评论、批评、建议等GitHub上的问题或提交拉取请求。可提供贡献说明在GitHub上的README中。贡献者列表是也可提供.
这个项目似乎获得了比我想象中更多的兴趣。截至2017年4月GitHub上超过1200个引用到repostatus.org徽章URL。我知道不希望成为这个项目的唯一决策者。我鼓励所有发现观看很有用GitHub上的回购并在讨论中提供反馈,尤其是与的问题讨论或“需要决策”标签。我正在处理代码更新,但我非常希望这个项目能够基于使用它的人的共识来推动。