关闭

保存和引用研究软件

开放科学的支柱

“软件应被视为合法且可引用的研究产品。”-软件引用原则

“不可再生的单一事件对科学没有意义”

-卡尔·波普尔,《科学发现的逻辑》,1934年

“有时,当你没有软件时,你就没有数据。”

-Christine Borgman,JNSO 2018

归档和引用软件工件的指南

全程指导你

三个简单步骤

软件遗产允许无缝存档您的研究软件工件,也可以添加到您的研究文章中精确参考到源代码的特定版本,一直到单个源文件的片段。这可以显著提高审阅者的工作经验(例如工件评估委员会)更广泛地说,你的所有读者(你的一个读者甚至可能是几周、几个月或几年后!)。 

步骤1:准备公共存储库

确保您的源代码托管在使用其中一个版本控制系统公开访问的存储库中(Github、Bitbucket、GitLab实例、机构软件伪造等)受Software Heritage支持目前为Subversion、Mercurial和Git。以下成熟的最佳实践,在源代码树的顶层包含以下文件:

  • 自述文件
    包含软件描述(名称、用途、网站指针、文档、开发平台、联系人和支持信息…)
  • 作者
    需要为软件记入贷方的所有人员的列表;如果您想指定每个人的角色,我们建议使用Inria阐述的贡献者分类.
  • 许可证
    项目许可条款。对于开放源代码许可证,请使用标准SPDX许可证名称。对于大型软件项目和开发人员,我们建议查看重新使用过程和工具。
  • A类代码元.json
    链接的数据元数据文件将有助于在Software Heritage存档中为源代码编制索引,并提供链接到其他相关研究输出的简单方法。请参阅代码元更多信息和我们的CodeMeta生成器工具。
第二步:保存代码

正确准备好代码存储库并更新后,您需要:

就这样,一切都完成了!无需创建帐户或提供任何类型的个人信息。如果您提供的url正确,Software Heritage将在不久后存档您的存储库及其完整的开发历史。如果您的存储库位于我们已知的一个主要伪造品上,则此过程只需几个小时;如果您指向我们以前从未见过的位置,可能需要更长的时间,因为我们需要手动批准它。请注意,您也可以使用专用软件遗产API入口点.

第三步:引用你的作品

源代码归档后,有很多方法可以在文章中引用它。三种常见的用例是

  • 将链接添加到完整存储库在Software Heritage中存档
  • 将链接添加到软件项目的精确版本
  • 将链接添加到源代码文件的精确版本,一直到代码行的级别。

完整存储库

通过在用于请求存档的URL前面加上前缀,可以获得到Software Heritage中存档的完整存储库(及其所有开发历史)的链接https://archive.softwareheritage.org/browse/origin。例如,如果您保存的存储库是https://github.com/rdicomoso/parmap,则指向Software Heritage中保存的版本的链接将为

https://archive.softwareheritage.org/browse/origin/https://github.com/rdicomoso/parmap/

通过此链接,您的读者可以广泛浏览存储库的内容深入研究其开发历史和/或目录结构,直至每个文件。

使用软件遗产固有标识符(SWHID)

软件遗产提供了完全文档化的标准标识符模式,已调用SWHID公司,为任何软件工件配备内在的标识符。可以找到使SWHID成为再现性标识符选择的特性的完整讨论在一篇专门的研究文章中,你可以在一篇专门的博客文章中了解更多关于其日益普及的信息.

SWHID可以配备一套丰富的限定符这可以精确地确定要查看给定工件的上下文。

这里我们只举几个例子说明如何使用它们。

项目的具体版本

以下SWHID标识了精确版本Parmap源代码的:

swh:1:版本:0064fbd0ad69de205ea6ec6999f3d3895e9442c2;原产地=https://github.com/rdicomoso/parmap

通过在SWHID前面添加前缀,可以将其转换为可点击的URLhttps://archive.softwareheritage.org/。因此,以下(超)链接将您直接带到Software Heritage中的一个页面,该页面正在浏览精确的版本(试试看!)

https://archive.softwareheritage.org/swh:1:rev:0064fbd0ad69de205ea6ec6999f3d3895e9442c2原产地=https://github.com/rdicomoso/parmap

获得正确SWHID的一个非常简单的方法是浏览Software Heritage中的存档代码,并导航到您感兴趣的修订版。然后单击永久链接垂直红色标签它出现在存档的所有页面上,在打开的选项卡中选择修订标识符。 

SWHID的版本1使用git-compatible散列,因此,如果您使用git作为版本控制系统,则只需在前面加上前缀即可创建正确的SWHIDswh:1:转速:到提交哈希。

代码片段

Software Heritage支持的SWHID允许您更进一步,通过使用行=限定符可用于指向文件的标识符。例如,以下SWHID展示了内容SWHID的所有可用限定符,指出了Parmap源代码中的核心映射算法,如2012年一篇描述Parmap的研究文章所述:

交换机:1:cnt:d5214ff9562a1fe78db51944506ba48c20de3379原产地=https://gitorious.org/parmap/parmap.git访问=swh:1:snp:78209702559384ee1b5586df13eca84a5123aa82;锚=swh:1:版本:0064fbd0ad69de205ea6ec6999f3d3895e9442c2;路径=/parmap.ml;行=101-143

点击测试这个链接:您将被无缝地带到Software Heritage存档中的一个页面上,该页面显示了相应的源代码,并突出显示了相关行。

在这里,您也可以通过导航到您对存档感兴趣的代码片段,单击片段第一行的行号,按住shift键并单击最后一行,然后打开permalinks选项卡来获得准确的链接。

软件的书目条目

最后但并非最不重要的是,biblatex软件,一种充分利用SWHID的书目风格是现在可从CTAN向BibLaTeX用户提供。请参阅文档在那里可以了解更多!

获取指南

Software Heritage最新版本的研究软件指南和LaTeX示例演练可在此处下载。

下载指南
为指南贡献力量

指南本身的源代码可用,并在CC-BY 4.0许可证下分发。欢迎您对其进行改进。它将定期更新。

访问指南的来源
加入社区

我们提供了一个邮件列表,用于在科学社区中共享软件遗产研究方面的信息,欢迎您加入。

订阅列表