软件遗产允许无缝存档您的研究软件工件,也可以添加到您的研究文章中精确参考到源代码的特定版本,一直到单个源文件的片段。这可以显著提高审阅者的工作经验(例如工件评估委员会)更广泛地说,你的所有读者(你的一个读者甚至可能是你几周、几个月或几年后!)。
地详细指南可在线获取,以及LaTeX示例,并将定期更新:我们鼓励您下载并查看它们以获得完整的详细信息。
在这篇博客文章中,我们总结了您需要采取的几个简单步骤:准备您的公共存储库,节约您在Software Heritage中的代码,以及参考它在您的工作中,在不同的粒度级别。
步骤1:准备公共存储库
确保您的源代码托管在使用其中一个版本控制系统公开访问的存储库中(Github、Bitbucket、GitLab实例、机构软件伪造等)受Software Heritage支持目前为Subversion、Mercurial和Git。
以下完善的最佳实践,在源代码树的顶层包含以下文件:
- 自述
- 包含软件描述(名称、用途、网站指针、文档、开发平台、联系人和支持信息…)
- 作者
- 需要为软件记入贷方的所有人员的列表;
如果要指定每个人的角色,我们建议使用
Inria阐述的贡献者分类.
- 许可证
- 项目许可条款。对于开放源代码许可证,请使用标准SPDX许可证名称.
第二步:保存代码
正确准备好代码存储库并更新后,您需要:
就这样,一切都完成了!无需创建帐户或提供任何类型的个人信息。如果您提供的url正确,Software Heritage将在不久后存档您的存储库及其完整的开发历史。
如果您的存储库位于我们已知的一个主要伪造品上,则此过程只需几个小时;如果您指向我们以前从未见过的位置,则可能需要更长的时间,因为我们需要手动批准它。
注意,您还可以使用专用软件遗产API入口点.
第三步:引用你的作品
一旦您的源代码被归档,有很多方法可以在您的文章中引用它。三种常见的用例是
- 将链接添加到完整存储库在Software Heritage中存档
- 将链接添加到软件项目的精确版本
- 将链接添加到源代码文件的精确版本,一直到代码行的级别。
完整存储库
通过在用于请求存档的URL前面加上前缀,可以获得到Software Heritage中存档的完整存储库(及其所有开发历史)的链接https://archive.softwareheritage.org/browse/origin.
例如,如果您保存的存储库是https://github.com/rdicomoso/parmap,则指向软件遗产中保存的版本的链接将为
https://archive.softwareheritage.org/browse/origin/https://github.com/rdicomoso/parmap/
通过此链接,您的读者可以广泛浏览存储库的内容,深入研究其开发历史和/或目录结构,直到每个文件。
项目的具体版本
软件遗产提供了完全文档化的标准标识符模式,已调用SWH-ID软件,用于指向精确版本它存档的所有源代码。
例如,以下SWH-ID标识精确版本Parmap源代码的:
swh:1:版本:0064fbd0ad69de205ea6ec6999f3d3895e9442c2;原产地=https://github.com/rdicomoso/parmap;
SWH-ID可以通过在其前面添加前缀来转换为可点击的URLhttps://archive.softwareheritage.org/。因此,以下(超)链接将您直接带到Software Heritage中的一个页面,该页面正在浏览精确的版本(试试看!)
https://archive.softwareheritage.org/swh:1:rev:0064fbd0ad69de205ea6ec6999f3d3895e9442c2;原产地=https://github.com/rdicomoso/parmap
获得正确SWH-ID的一个非常简单的方法是浏览Software Heritage中存档的代码,并导航到您感兴趣的修订版。然后单击永久链接垂直红色标签它出现在存档的所有页面上,在打开的选项卡中选择修订标识符:示例如下图所示:
右下角的两个方便的按钮允许您复制剪贴板中的标识符或完整的永久链接,以便根据需要插入到文章中。
SWH-ID的版本1使用git-compatible散列,因此,如果您使用git作为版本控制系统,则只需在前面加上前缀即可创建正确的SWH-IDswh:1:转速:到提交哈希。
代码片段
Software Heritage支持的SWH-ID允许您更进一步,通过使用行=限定符可用于指向文件的标识符。
例如,以下SWH-ID指向Parmap源代码中的核心映射算法,如2012年描述Parmap的一篇研究文章所示:
swh:1:cnt:d5214ff9562a1fe78db51944506ba48c20de3379;起源=https://github.com/rdicomoso/parmap;线路=101-143
点击测试这个链接:您将在一个显示相应源代码的页面上无缝地进入软件遗产档案,并突出显示相关行。
在这里,您也可以通过导航到您对存档感兴趣的代码片段,单击片段第一行的行号,按住shift键并单击最后一行,然后打开permalinks选项卡来获得准确的链接
结论
我们希望您会感激Software Heritage能够轻松存档您的软件源代码,并且它为增强您的研究文章提供了强大的SWH-ID功能和灵活性。
期待着您能为这一切做些什么!