Artifact：面向每个人的设计文档

• 安装指南
• 快速入门指南
• 速查表
• 常见问题解答
• 简单质量手册
• 渲染设计文档
• 问题跟踪器

Artifact 是面向每个人的简单、可链接和可跟踪的设计文档工具。它允许任何人编写和链接他们的设计文档，无论是相互之间还是与源代码之间，使得了解项目完成情况变得容易。文档可以进行版本控制，可以在浏览器中编辑，并提供完整的命令行工具用于搜索、显示、检查、导出和格式化。

编写详细的设计文档是高质量软件开发的核心支柱之一。设计文档是您捕获项目需求（目的）并将其与规范（您将如何构建它）链接的方式。它们让您在编写代码之前将想法记录在纸上，并帮助您减少痛苦的代码重构。它们为开发者和好奇的用户提供参考，说明了您的项目为何以及如何以某种方式开发，并在必要时更容易地对项目进行重构。

尽管设计文档对于软件质量至关重要，但编写它们的工具以及将它们集成到项目更大背景中的工具非常有限。Artifact 通过使编写良好的设计文档对普通开发者有用，旨在填补质量最佳实践中的主要差距。

首先，artifact 使得通过指定 partof 属性来轻松在 文本文件 中编写设计文档并链接它们。这允许开发者将设计文档纳入版本控制，使用常规代码审查工具进行审查，并使用所有常规文本处理工具（vim、grep、sed 等）来查看、编辑和重构它们。Artifact 还提供了一些自己的命令行工具。

其次，设计文档可以通过一种与语言无关的语法链接到源代码（在源代码的任何位置都可以使用#ART-name）。一旦链接，任何阅读注释的人都可以轻松地查找相关的设计文档。同样，任何人查看Web UI都可以看到规范或测试在代码中的具体实现位置。此外，如果设计文档的名称更改，art check将告诉您悬挂引用的位置。您再也不必担心重构设计文档，因为您的代码中的引用会过时。

最后，artifacts会将您的设计文档渲染成精美的视图并导出到类似github-sites（示例）的网站，您可以使用art serve在浏览器中编辑。这完成了自文档化的特性，并允许任何人（甚至非开发者！）查看和编辑其项目的文档。

以这种方式，artifacts旨在统一其他质量最佳实践，同时使编写设计文档在您日常开发工作中更加有趣和有用。

通过youtube广告和快速入门指南开始使用artifacts。

支持项目

您可以通过在github上⭐收藏项目并💚与您的朋友、同事和社交媒体分享来支持该项目。您还可以直接在patreon上支持它，在2017 Hackaday Prize上投票支持它，并通过留下直接反馈来支持它。

通过上述任何链接收集的资金将仅用于聘请学生开发者作为实习生，在artifacts中开发开源功能。从这些来源收到的资金不会用于我（Garrett Berg）或专有软件开发。

通过支持artifacts，您正在支持开源质量软件开发工具以及学生实习生机会。谢谢！

稳定性

artifacts是1.0软件，对向后兼容性有强烈的承诺。1.0版本是“开源”版本。artifacts已准备好供任何规模的项目使用，作为其默认设计文档工具，但外部工具可能仍然缺乏针对企业客户的工具。

2.0版本将专注于稳定外部工具库。这将使artifacts能够与JIRA等行业工具以及外部回归测试跟踪软件集成。我目前正在寻求企业支持，请考虑在patreon上支持此项目。

以下API是稳定的，应始终保持向后兼容性

• Artifact .toml文件。功能可以添加，但不应该删除。这包括
  • Artifact类型：REQ，SPC，TST。
  • Artifact字段：partof，text，done。
  • 文本格式：默认为markdown，带有[[ART-name]]链接。
• Artifact关系：显式partof，自动按名称链接等。
• 从其关系计算出的Artifact完整性。
• 源代码链接：在源代码的任何位置使用#ART-name标记artifacts为完成。
• .art/settings.toml文件
• 命令行界面，包括
  • 命令名称（如tutorial、init、ls、check、fmt等）。
  • 每个命令现有的标志。
  • 完成的功能检查（即悬空工件名称）。
  • art serve在本地主机的默认端口为5373。

以下内容在2.0版本之前应该相对稳定，但可能有一些小的调整。

• 命令的输出，包括
  • 输出消息的格式。即，你不应该依赖于art ls具有特定的输出格式。
  • 由art fmt执行的工件格式。
• 由art ls --json返回的json格式以及通过art serve的json-rpc服务器。
• 第一部分未提到的任何内容。如果你不确定，请提交一个工单。

以下内容在2.0版本之前预计会有很大变化

• Web UI。希望这些变化将对所有人几乎是一致的改进。
• art serve的http界面，包括其API方法和数据格式。
• 库本身的代码和预期的函数/类型等应被视为高度不稳定。未来的工作将涉及将其拆分成更稳定的更小的crate。
• 使用art -v触发的日志消息。
• 许多其他我无法想到的事情。如果你不确定或担心，请提交一个工单。

工件将继续使用持续发布周期，具有广泛的单元和集成测试。还将有一个用于新功能和实验功能的beta发布渠道。如果你发现了一个错误，请提交一个工单。

许可

目标

工件许可的意图是

• 工件应用对任何人开放源代码，可用于任何目的（双重许可MIT + Apache）。
• 用户可以按任何方式对工件生成的任何内容进行许可，包括构建的静态HTML页面。
• 任何工件（除代码和标志外）的文档、教程或规范均属公共领域，可用于任何目的。

具体说明

工件应用的所有文档和教程均在CC0创意共享公共领域许可下发布，目的是让你自由地复制、粘贴和修改任何设计、指南、示例或导出数据，用于任何目的（包括商业目的），无需署名。你可以在这里了解更多关于CC0的信息：https://creativecommons.org/publicdomain/

CC0许可适用于

• 所有项目文档
• 工件设计文档（也位于design/中）
• 工件文档（位于docs/中），但不在docs/logo中的标志
• 工件Wiki
• 由任何工件命令创建的任何文件或数据，包括
  • 由art init创建的文档
  • 由art tutorial创建的文档
  • 由art export创建的编译HTML/CSS/JSON文件

工件标志（命名为Tula）根据Creative Commons Attribution-ShareAlike（《CC BY-SA》）许可，可以在工件项目中用于任何目的，无需额外署名。工件标志位于docs/logo，最初由packapotatoes创建。

源代码许可

源代码许可协议为以下之一

• Apache License，版本 2.0，(LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT 许可协议 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任选其一。

除非您明确表示，否则根据 Apache-2.0 许可协议定义，您有意提交给作品作为贡献的内容，应按上述方式双重许可，不附加任何额外条款或条件。