关闭

HOWTO存档并引用您的代码

正确存档和引用源代码是实现支持开放科学和至遵守了解您的软件原则(KYSW)。本页提供了使用Software Heritage无缝执行此操作的简明清单。

步骤1:准备公共存储库

  • 添加README文件
  • 添加AUTHORS文件
  • 使用两种推荐的方法之一添加许可证信息
  • (可选)添加包含机器可读元数据的codemeta.json文件(可以使用代码元生成器

现在公认的做法是也添加README文件的标记版本,但请将AUTHORS和LICENSE文件保留为纯文本。

步骤2:将代码保存在软件遗产中

有几种方法可以确保您的代码被存档,具体取决于您首选的工作流以及它的宿主位置。它们总结如下,选择一个最适合你的。

通过浏览器扩展手动更新

对于托管在Bitbucket、GitHub、GitLab.com或任何GitLab实例上的项目,最好通过安装专用的Updateswh浏览器扩展,可用于Chrome和Firefox.

手动通过立即保存代码窗体

  • 转到软件遗产立即保存代码页面
  • 在下拉列表中选择适当的版本控制系统(目前支持git、svn和hg)
  • 输入代码存储库引用URL
    注意:。这一定是允许您从存储库克隆或签出项目的url! 如果有疑问,可以使用适当的命令在临时目录中克隆/签出项目,从而对其进行双重检查。以下是git、svn和hg的示例:

    • git克隆<您的url>
    • svn签出<您的url>
    • hg克隆<您的url>
  • 单击提交按钮。

通过API自动

可以通过以下方式以编程方式触发存储库的存档软件遗产API,这使您能够将存档作为任何开发工作流的一部分。如果您使用许多流行的代码托管平台之一,我们建议您使用特定的API端点专为网钩这些平台中的一个:看看带有详细示例和文档的专用博客帖子对于Bitbucket端点,Gitea端点,GitHub端点,GitLab端点(及其所有实例),以及SourceForge端点.

下面是如何在GitHub上配置webhook的示例,您可以在其中看到建议的设置:在创建分支、标记或发布时触发存档,而不是在每次推送事件时触发存档.

获取目录的SWHID

在GitHub上,您还可以使用GitHub操作,这可能更容易配置,但要记住,为了相同的最终结果,它在幕后使用的资源要比webhook调用多得多。

第三步:引用代码

要正确引用代码,请使用软件遗产标识符(SWHID),该标识符可以从软件遗产存档中获得,如下所示。

获取完整目录的SWHID

导航到目录你感兴趣(你可以使用浏览器扩展以快速找到存档的存储库),并拉出红色永久链接选项卡,如下图所示,然后将SWHID标识符或永久链接复制到剪贴板,以便插入到文档中。

获取目录的SWHID

获取代码片段的SWHID

您还可以获取文件的SWHID,或文件中的代码片段。为此,首先导航到该文件,通过单击第一行的行号选择(可选)感兴趣的代码片段,然后按住shift-click键单击最后一行的行号。然后,拉出红色的Permalinks选项卡并复制SWHID标识符或相应的Permallink。

获取代码片段的SWHID

LaTeX用户

如果您使用LaTeX作为文档,那么您会喜欢biblatex软件软件包:它允许您为软件生成漂亮的书目条目,并且它本身支持SWHID。Biblatex软件集成在CTAN和TeXLive中,在Overleaf中开箱即用(这里是一个ACM官方文章样式的模板文档). 截至2022年4月,biblatex软件集成于ACM文章风格.

以下是从文章中摘录的示例“使用软件遗产存档和引用源代码”,ICMS 2020。尝试单击链接查看结果,观看下面的教程了解更多信息,以及阅读文档根据你的口味进行调整。

参考文献

[1] [SW]罗伯托·迪·科斯莫和马可·丹拉蒂托,Parmap库y、 2012年。巴黎迪德罗大学和比萨大学。许可证:LGPL-2.0。网址:https://rdicomoso.github.io/parmap网址/

[2] [SW Rel.]Roberto Di Cosmo和Marco Danalpto,Parmap库版本0.9.8, 2012. 巴黎迪德罗大学和比萨大学。基因:LGPL-2.0。斯威德:<swh:1:版本:0064fbd0ad69de205ea6ec6999f3d3895e9442c2;原产地=https://gitorious.org/parmap/parmap.git;访问=swh:1:snp:78209702559384ee1b5586df13eca84a5123aa82>

[3] [SW除外]罗伯托·迪·科斯莫(Roberto Di Cosmo)和马可·丹拉蒂托(Marco Danalpto),“岩芯测绘程序“,来自Parmap库版本0.9.8, 2012. 巴黎狄德罗大学和比萨大学。许可证:LGPL-2.0。斯威德:<swh:1:cnt:d5214ff9562a1fe78db51944506ba48c20de3379;原产地=https://gitorious.org/parmap/parmap.git;visit=swh:1:snp:78209702559384ee1b5586df13eca84a5123aa82;锚=swh:1:版本:0064fbd0ad69de205ea6ec6999f3d3895e9442c2;路径=/parmap.ml;线路=101-143>