Keywords

1 Introduction

Software source code is an essential research output, and there is a growing general awareness of its importance for supporting the research process [6, 20, 27]. Many research communities focus on the issue of scientific reproducibility and strongly encourage making the source code of the artefact available by archiving it in publicly-accessible long-term archives; some have even put in place mechanisms to assess research software, like the Artefact Evaluation process introduced in 2011 and now widely adopted by many computer science conferences [7], and the Artifact Review and Badging program of the ACM [4]. Other raise the complementary issues of making it easier to discover existing research software, and giving academic credit to authors [21, 22, 25].

These are important issues that are similar in spirit to those that led to the current FAIR data movement [28], and as a first step it is important to clearly identify the different concerns that come into play when addressing software, and in particular its source code, as a research output. They can be classified as follows:

  • Archival: software artifacts must be properly archived, to ensure we can retrieve them at a later time;

  • Reference: software artifacts must be properly referenced to ensure we can identify the exact code, among many potentially archived copies, used for reproducing a specific experiment;

  • Description: software artifacts must be equipped with proper metadata to make it easy to find them in a catalog or through a search engine;

  • Citation: research software must be properly cited in research articles in order to give credit to the people that contributed to it.

As already pointed out in the literature, these are not only different concerns, but also separate ones. Establishing proper credit for contributors via citations or providing proper metadata to describe the artifacts requires a curation process [2, 5, 18] and is way more complex than simply providing stable, intrinsic identifiers to reference a precise version of a software source code for reproducibility purposes [3, 16, 21]. Also, as remarked in [3, 20], resarch software is often a thin layer on top of a large number of software dependencies that are developed and maintained outside of academia, so the usual approach based on institutional archives is not sufficient to cover all the software that is relevant for reproducibility of research.

In this article, we focus on the first two concerns, archival and reference, showing how they can be addressed fully by leveraging the Software Heritage universal archive [1], and also mention some recent evolutions in best practices for embedding metadata in software development repositories.

In Sect. 2 we briefly recall what is Software Heritage and what makes it special; in Sect. 3 we show how researchers can easily ensure that any relevant source code is archived; in Sect. 4 we explain how to use the intrinsic identifiers provided by Software Heritage to enrich research articles, making them more useful and appealing for the readers, and providing stable links between articles and source code in the web of scientific knowledge we are all building. Finally, we point to ongoing collaborations and future perspectives in Sect. 5.

2 Software Heritage: The Universal Archive of Software Source Code

Software Heritage [1, 17] is a non profit initiative started by Inria in partnership with UNESCO, to build a long term universal archive specifically designed for software source code, and able to store not only a software artifact, but also its full development history.

Software Heritage’s mission is to collect, preserve, and make easily accessible the source code of all publicly available software. Among the strategies designed for collecting the source code there is the development of a large scale automated crawler for source code, whose architecture is shown in Fig. 1.

Fig. 1.
figure 1

Architecture of the Software Heritage crawler

Full size image

The sustainability plan is based on several pillars. The first one is the support of Inria, a national research institution that is involved for the long term. A second one is the fact that Software Heritage provides a common infrastructure catering to the needs of a variety of stakeholders, ranging from industry to academia, from cultural heritage to public administrations. As a consequence, funding comes from a diverse group of sponsors, ranging from IT companies to public institutions.

Finally, an extra layer of security is provided by a network of independent, international mirrors that maintain a full copy of the archiveFootnote 1.

We recall here a few key properties that set Software Heritage apart from all other scholarly infrastructures:

  • it proactively archives all software, making it possible to store and reference any piece of publicly available software relevant to a research result, independently from any specific field of endeavour, and even when the author(s) did not take any step to have it archived [1, 17];

  • it stores the source code with its development history in a uniform data structure, a Merkle DAG [23], that allows to provide uniform, intrinsic identifiers for the billions of software artifacts of the archive, independently of the version control system or package format used [16].

At the time of writing this article, the Software Heritage archive contains over 7 billions unique source code files, from more than 100 million different software originsFootnote 2.

It provides the ideal place to preserve research software artifacts, and offers powerful mechanisms to enhance research articles with precise references to relevant fragments of your source code. Using Software Heritage is straightforward and involves very simple steps, that we detail in the following sections.

3 Archiving and Self Archiving

In a research article one may want to reference different kinds of source code artifacts: some may be popular open source components, some may be general purpose libraries developed by others, and some may be one’s own software projects.

All these different kinds of software artifacts can be archived extremely easily in Software Heritage: it’s enough that their source code is hosted on a publicly accessible repository (Github, Bitbucket, any GitLab instance, an institutional software forge, etc.) using one of the version control systems supported by Software Heritage, currently Subversion, Mercurial and GitFootnote 3.

For source code developed on popular development platforms, chances are that the code one wants to reference is already archived in Software Heritage, but one can make sure that the archived version history is fully up to date, as follows:

Fig. 2.
figure 2

The save code now form

Full size image

That’s all. No need to create an account or disclose personal information of any kind. If the provided URL is correct, Software Heritage will archive the repository shortly after, with its full development history. If it is hosted on one of the major forges we already know, this process will take just a few hours; if it is in a location we never saw before, it can take longer, as it will need to be manually screenedFootnote 5.

3.1 Preparing Source Code for Self Archiving

In case the source code is one own’s, before requesting its archival it is important to structure the software repository following well established good practices for release management [24]. In particular one should add README and AUTHORS files as well as licence information following industry standard terminology [19, 26].

Future users that find the artifact useful might want to give credit by citing it. To this end, one might want to provide instructions on how one prefers the artifact to be cited. We would recommend to also provide structured metadata information in machine readable formats. While practices in this area are still evolving, one can use the CodeMeta generator available at https://codemeta.github.io/codemeta-generator/ to produces metadata conformant to the CodeMeta schema: the JSON-LD output can be put at the root of the project in a codemeta.json file. Another option is to use the Citation File Format, CFF (usually in a file named citation.cff).

4 Referencing

Once the source code has been archived, the Software Heritage intrinsic identifiers, called SWH-ID, fully documented online and shown in Fig. 3, can be used to reference with great ease any version of it.

Fig. 3.
figure 3

Schema of the core Software Heritage identifiers

Full size image

SWH-IDs are URIs with a very simple schema: the swh prefix makes explicit that these identifiers are related to Software Heritage; the colon (:) is used as separator between the logical parts of identifiers; the schema version (currently 1) is the current version of this identifier schema; then follows the type of the objects identified and finally comes a hex-encoded (using lowercase ASCII characters) cryptographic signature of this object, computed in a standard way, as detailed in [15, 16].

These core identifiers may be equipped with the qualifiers that carry contextual extrinsic information about the object:

  • origin : the software origin where an object has been found or observed in the wild, as an URI;

  • visit : persistent identifier of a snapshot corresponding to a specific visit of a repository containing the designated object;

  • anchor : a designated node in the Merkle DAG relative to which a path to the object is specified;

  • path : the absolute file path, from the root directory associated to the anchor node, to the object;

  • lines : line number(s) of interest, usually within a content object

The combination of the core SWH-IDs with these qualifiers provides a very powerful means of referring in a research article to all the software artefacts of interest.

To make this concrete, in what follows we use as a running example the article A “minimal disruption” skeleton experiment: seamless map and reduce embedding in OCaml by Marco Danelutto and Roberto Di Cosmo [9] published in 2012. This article introduced Parmap [12], an elegant library for multicore parallel programming that was distributed via the gitorious.org collaborative development platform, at gitorious.org/parmap. Since Gitorious has been shut down a few years ago, like Google Code and CodePlex, this example is particularly fit to show why pointing to an archive of the code is better than pointing to the collaborative development platform where it is developed.

4.1 Specific Version

The Parmap article describes a specific version of the Parmap library, the one that was used for the experiments reported in the article, so in order to support reproducibility of these results, we need to be able to pinpoint precisely the state(s) of the source code used in the article.

The exact revision of the source code of the library used in the article has the following SWH-ID:

figure a

This identifier can be turned into a clickable URL by prepending to it the prefix https://archive.softwareheritage.org/ (one can try it by clicking on this link).

Fig. 4.
figure 4

Code fragment from the published article compared to the content in the Software Heritage archive

Full size image

4.2 Code Fragment

Having a link to the exact archived revision of a software project is important in all research articles that use software, and the core SWH-IDs allow to drill down and point to a given directory or even a file content, but sometimes, like in our running example, one would like to do more, and pinpoint a fragment of code inside a specific version of a file. This is possible using the lines= qualifier available for identifiers that point to file content.

Let’s see this feature at work in our running example, showing how the experience of studying or reviewing an article can be greatly enhanced by providing pointers to code fragments.

In Figure 1 of [9], which is shown here as Fig. 4a, the authors want to present the core part of the code implementing the parallel functionality that constitutes the main contribution of their article. The usual approach is to typeset in the article itself an excerpt of the source code, and let the reader try to find it by delving into the code repository, which may have evolved in the mean time. Finding the exact matching code can be quite difficult, as the code excerpt is often edited a bit with respect to the original, sometimes to drop details that are not relevant for the discussion, and sometimes due to space limitations.

In our case, the article presented 29 lines of code, slightly edited from the 43 actual lines of code in the Parmap library: looking at Fig. 4a, one can easily see that some lines have been dropped (102–103, 118–121), one line has been split (117) and several lines simplified (127, 132–133, 137–142).

Using Software Heritage, the authors can do a much better job, because the original code fragment can now be precisely identified by the following Software Heritage identifier:

figure b

This identifier will always point to the code fragment shown in Fig. 4b.

The caption of the original article shown in Fig. 4a can then be significantly enhanced by incorporating a clickable link containing the SWH-ID shown above: it’s all is needed to point to the exact source code fragment that has been edited for inclusion in the article, as shown in Fig. 5. The link contains, thanks to the SWH-ID qualifiers, all the contextual information necessary to identify the context in which this code fragment is intended to be seen.

Fig. 5.
figure 5

A caption text with the link to the code fragment and its contextual information

Full size image

When clicking on the hyperlinked text in the caption shown above, the reader is brought seamlessly to the Software Heritage archive on a page showing the corresponding source code archived in Software Heritage, with the relevant lines highlighted (see Fig. 4b).

4.3 Software Bibliographies with biblatex-software

Another way to enrich an article with precise pointers to software source code is by adding entries for it in the bibliography. Unfortunately, standard bibliography styles do not treat software as a first class citizen, and for example BibTeX users often resort to the @misc entry to this end, which is really unsatisfactory.

Since April 2020, users of the BibLaTeX package can leverage the biblatex-software package [10], available on CTAN [8], to produce rich software bibliographies.

This package support four kind of different entries:

  • @software for describing the general information about a software project

  • @softwareversion for describing a specific version or release of a software project

  • @softwaremodule for describing a module that is part of a larger software project

  • @codefragment for describing a fragment of code (full file, or selected lines of a file)

Using these special BibTeX entries, the various examples presented in the previous sections above can be described as follows

figure c

The result can be seen in the bibliography of this article as [13, 14].

4.4 Getting the SWH-ID

A fully qualified SWH-ID is rather long, and it needs to be, as it contains quite a lot of information that is essential to convey. In order to make it easy to use SWH-IDs, we provide a very simple way of getting the right SWH-ID without having to type it by hand. Just browse the archived code in Software Heritage and navigate to the software artifact of interest. Clicking on the permalinks vertical red tab that is present on all pages of the archive, opens up a tab that allows to select the identifier for the object of interest: an example is shown in Fig. 6.

The two buttons on the bottom right allow to copy the identifier or the full permalink in the clipboard, and to paste it in an article as needed.

Fig. 6.
figure 6

Obtaining a Software Heritage identifier using the permalink box on the archive Web user interface

Full size image

4.5 Generating and Verifying SWH-IDs

An important consequence of the fact that SWH-IDs are intrinsic identifiers is that they can be generated and verified independently of Software Heritage, using swh-identify, an open source tool developed by Software Heritage, and distributed via PyPI as swh.model, with the stable version at the time of writing being this one.

Version 1 of the SWH-IDs uses git-compatible hashes, so if the source code that one wants to reference uses git as a version control system, one can create the right SWH-ID by just prepending swh:1:rev: to the commit hash. This comes handy to automate the generation of the identifiers to be included in an article, as one will always have code and article in sync.

5 Perspectives for the Scholarly World

We have shown how Software Heritage and the associated SWH-IDs enables the seamless archival of all publicly available source code. It provides for all kind of software artifacts the intrinsic identifiers that are needed to establish long lasting, resilient links between research articles and the software they use or describe.

All researchers can use right now the mechanisms presented here to produce improved and enhanced research articles. More can be achieved by establishing collaborations with academic journals, registries and institutional repositories and registries, in particular in terms of description and support for software citation. Among the initial collaborations that have been already established, we are happy to mention the cross linking with the curated mathematical software descriptions maintained by the swMath.org portal [5], and the curated deposit of software artefacts into the HAL french national open access portal [18], which is performed via a standard SWORD protocol inteface, an approach that is currently being explored by other academic journals.

We believe that the time has come to see software become a first class citizen in the scholarly world, and Software Heritage provides a unique infrastructure to support an open, non profit, long term and resilient web of scientific knowledge.