Archiving and referencing research software in Software Heritage
CC Attribution 3.0 Germany:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor.
Di Cosmo, Roberto
We show why and how to archive, reference and cite software in research articles using the Software Heritage archive and identifiers, as well as the dedicated biblatex-software package available on CTAN as:-archive/macr...
 I'm delighted to take part in ICMS 2020, and especially so because I have the occasion to tell you more about software heritage and how you can use it to archive and reference all the source code in the world. The reason why we want to do this is that software source code is knowledge and not any kind of knowledge, a very special kind of knowledge because it is written by humans, for humans to read, and also sufficiently technically detailed to be executable by machine. This is not a new observation when I was a student, I was reading a book by Yarrow Davenson, and in the introduction I found this beautiful phrase, I mean, programs must be written for people to read, and only incidentally for machines to execute. I mean, back then there was not much source code available, so this could just seem a phrase you say to your students, tell them they need to turn in your homework, your CS class in a readable way, otherwise they will get bad grades, but it's much deeper than that. The point is that when you write a piece of software you know it with a ball, you might have errors, you need to reuse it, modify it, adapt it, and so you need to be able to read it later on. Today, 30 years later, we have access to an incredible amount of open source code, and so we can find jewels like this excerpt of the Apollo 11 guidance computer source code, which was used to control the Apollo mission, or this particularly amusing function that computes one over a square root of X for floating numbers, but without using any floating point co-processor at all. As then Schuster, the board director of the Computer History Museum, used to write a few years ago, but actually source code, it opens up a view in the mind of the designers. Well, but when we now focus on research, our day-to-day activity, it's easy to see that software source code is one of the three key pillars of open science. We tend to think a lot about articles, they are super important, about data, we need data to be able to do our computation evaluations, but for too long software has been forgotten, and software is essential to understand what kind of transformation you're actually doing. Well, once we notice that we have open science, we need these three pillars, and that we need to focus on building the missing one, which is the one for software source code, in particular open source one, then we discover that we need to cater to a plurality of needs, depending on the different kind of actors in research. One kind of actor researcher, you, me here, we just want to be able to find a place where we can safely archive the software used in our articles, and find a way to provide precise references to the software we archive, so our readers or ourselves can get back to the exact version we used. We need to be able to look at the software, find useful, we need to get credit for what we do, we want to be able to tinker with the software others to adapt it to improve it. But then other actors, like collaborators or team, they need to track the software contribution, you know, as usually, at least to have a web page, more than often to produce reports, and if you go up in the hierarchy, you will find top-level research organization, ministry research, etc., and they want to know what kind of software assets they are contributing to. Well, if you think a little bit carefully to address all these needs, there are at least four different things we need to do, and I will try to present them to you in what I believe is the real order of difficulty. First of all, we need a place where to archive software. It is a place where you put something and you can find it again. I mean, this is essential for reproducibility, if you cannot find the software for your paper, what can you do? Then a little bit more difficult, actually, you need to have proper identification. I pretend this is more difficult than just archiving because putting a zip file somewhere is very easy to do, but if you just use a URL to link to it, well, reproducibility is not actually really guaranteed. Then you need to have proper metadata for this cramming software. It is more complex than the previous levels because there are too many ontologies out there. Finally, you need to get credit, citation, this is important for the evaluation, etc. This is a more touchy subject because we need to decide who is the author, who is not, who did what, etc. So it's more political or human level, so less technical, more complex to do it properly. Well, to address all these things in a proper way, we need an infrastructure which is actually designed for software. Well, the good news is, now we have one. At least for addressing the first two issues I take here, archival and identification. So let me introduce you to software heritage. Software heritage is an initiative which was started over five years ago with a clear mission to go out, collect, or the source code of all software publicly available, preserve it and make it available to everybody. If you want to have an idea of how to think about software heritage at a very high level, first of all it is a reference catalog. Today we have a source code available from so many different platforms, I mean code hosting platform like Github, Distribution, like Debian or many, many other places. And we need a central place where we have a catalog of everything that exists. We are building this. The other thing which is important is that we are building an archive. Unfortunately, for quite a long time we kind of misunderstood the development platform for archives. The development platform is not an archive. It's a place where I go, I create a project, work with others to improve it. Sometimes I can rename it, remove it, move it elsewhere so there is no guarantee that what I can find here today, I will find it tomorrow. An archive was surely missing. We are building it. And finally, we are also starting to build an infrastructure that allows to research on the global scale or not the source code which is available because we collect it, we archive it in a uniform way. So it's also an incredible data set for doing research. Well, how will you do to go out, collect, preserve and share all the source code all the work? Let me give you a brief overview of what we are doing. What we are building is a system that goes out and actually harvest source code from all different platforms that we can discover and that we can connect to. This is not an easy task because it is not like an archive in the web. We do not have a standard for communicating for crossing or distribution platform. So talking to GitHub is not the same as talking to Merkurial or sorry, to be bucket or to GitHub, etc. And so we need to build that after one at a time. Once we do this, we can get a list of tons and tons of different software projects, maintaining using different version control system, different package formats, etc. And since we are here for the long run, we do not stop there. We just don't make a scene, a copy of what we found out there. We go the extra mile and actually convert all the different version control system, all the different package formats, all the information we can get out there into a single universal data format, which is basically a gigantic Merkel-Direct Secret Graph. Today, we have already archived more than 8 billion unique source files for more than 130 million software origins. And I would like to spend a little bit of time on the peculiarity of this Merkel Graph. You have to know that all the nodes in the graph here represent either file contents or directories or revisions or commits, releases, etc. And to each of these nodes, we associate a unique identifier, which is computed from the object itself through cryptographic functions. And these are the software heritage identifiers or suites. The general scheme of a software heritage identifier is like this. You have a prefix, SWH, which is registered with the IRNAT today. The schema version, up to now we are using version 1, a tag that tells you what is the object that is defined here, and then the identifier, which is the hash, the cryptography hash. As kind of object, we have contents, directories, revisions, releases, or snapshots. You can also add some extra qualifiers that allow you to describe to the reader or the user of this identifier where you find the software from, in which position, inside the graph, what are the lines which you are interested in, and so on. This is becoming a standard in industry. I mean, now it is part of the Dinos Foundation SPDX definition. You can find it also in WikiData, and you can click on these links to see some examples if you're interested, but we'll demo it right away. Now why software heritage is special for research software in particular? First of all, it is a universal archive. This means it collects really all software, not just academic software. So if your research software actually depends on external libraries, chances are we are collecting them. The other point is that we are actually proactively harvesting codes. So we do it without waiting for somebody depositing it in. And that's the reason why we have so many project archive right now. All this means that probably some of your software may be there already. You could check right now. If it is not, you can actually save it now in that position. The other important point is that we provide identifier. This screen I have briefly shown to you, and we see it in the demo right away. They are intrinsic. They do not depend on any kind of register. So decentralized, cryptographically strong. You can verify that what you download or what you find that has this identified is actually the same software that was mentioned in an article, the reference it. You can use them to enhance articles for better reproducibility. And also more recently released a Biblatex style that allows you actually to cite software properly in your papers with pointers to software usage suites. Their detailed guidelines are in the paper and also available online. And now I think the moment I scan to stop talking and start doing, so let's start to look at a little bit of a demo of how we can use all this. To see how using software heritage can improve the way we write articles or research articles that are mentioned or include software, well, let's try to have a look at what I actually did a few years ago. Here is the list of my publications. If you look in 2012, here is an article that I wrote with a friend about a particularly interesting implementation of MapReduce. Here is a local copy of the paper. Let me put it full screen. So it is 2012. Typical paper in functional programming and parallel programming, a little bit of mathematical description of the operation you want to perform. Then we go down to the implementation section here. We actually found a way to implement this processing schema, a particularly nifty way. We're very proud of it. That's the reason why we actually go through the lines of code, stepping one by one and telling the reader why this is doing any job in a proper way. Here is a copy of the key algorithm that ImplementSmapReduce uses in some very nifty trick with a Unix memory mapping system. Well, okay. So 29 lines. We are proud of it. We describe it. Then we do some tests to show the data actually scales up, etc. That's fantastic. But then if you want to play with this software and use it and check that what we say was correct, how can you do it? Already back then into 2012, I was very fond of being open access, open source, open data, etc. So at the end of the article you see, we say that the full source code of the library is available under a free software license, LGPL, from a development platform. Back then I was mistaking developing platform for archives. And it was also incorporated in a Gordy installation system for the OCaml programming language. When unfortunately three years later, Gitorios was shut down. So there is no point in clicking here. You will find nothing. And also unfortunately, the Gordy installation system has gone away. We've got another one called Open, to which I contributed. So you find this paper, you read it, you get excited about a particular implementation of the algorithm and there are nothing you can, despite all my good will to try to do my best, the best that was available a few years ago. Well, today things have changed quite a bit. You see, for example, here, this is the same paper. The only difference you see now is that in 2020 I had taken exactly the same latex source of this paper and have made some minor modification using what is available today with software access. So one minor modification is that just below the source code, which is the snippet of source code which is shown in the paper. Now I added this little phrase with a pointer to actually the suite of the software identifier for the source code that corresponds to what is shown here. Look at it. You see there is a resolver part, archive.sortware.org, and then followed by this from the suite with all the extra qualifiers that allow to put it in context. If I click here, what happens when I am brought exactly, exactly in the software architecture archive in front of the exact code fragment that is mentioned in the article with all the necessary contextual information. So you see here is a commit where it is located, this file, the path inside the commit so you may know the name of the file, etc. And actually if you look at this you will see that well the code in the paper does not really perfectly match what you see in the archive. Let me put it a little smaller here. Here are 29 lines and here are a bit more than 29 lines. But actually the point is that to fit into the page element we had to remove some lines and we just removed some exception. And we did really change the overall function of the algorithm that you see if you try to reproduce it's not the same. So it's much better to have a link there. And the other modification we made is at the end of the article where we were mentioning the full version control system on GitTorios which is now gone. We also added a link to the archived copy on software heritage which allows us to get to the latest status of the archived copy on the software edge of this particular repository. Here we have all the history available, all the commits of the version etc. which are available for you. So that's great. It's really a game changer for what we plan to do with the research software today. And it's not all because you can also actually cite the software today. You will see in the paper we can use this new bibliotech style to describe the software in this Parma library. The particular version, the version we used in the paper, the particular snippet that corresponds to it, I mean this is actually what you have seen in the presentation a few minutes ago. And you can find them in the bibliography properly highlighted as software release or software excerpt, I think, with the suites which are also perfectly clickable. And I hope you like this demo. In any case, in the slides that you can download online, you will have pointers to the things we have seen and also to a lot more material I do not have time to show you today. And time to go to the conclusion. I would like to say, first of all, I mean software is really an open universal initiative. We really try to make it clear how international, independent, non-profit, long term initiative it is. That is the reason why we have partnership with UNESCO. On the other side, all this work has been started thanks to INRIA support, which was fundamental to start the effort five years ago. And now we are bringing together many different sponsors and partners. So you see there is a lot of space here, there is space for more to come people to come. I hope to have convinced you the software is special. It's a universal archive. It provides intrinsic identifiers. It's open, non-profit, long term. It's an infrastructure for open science. And then you can help. Use software heritage in your article, in your conference, in your journals, in your proceedings. See what the people in SSWMART or IPOL are already doing. Do the same in other conferences. If you find software which is not saved already, please do trigger the archive of the software in our archive. You can contribute to software heritage. Everything is open source. Just spread the word. Tell other people about what is going on. When I will stop here, if you want to learn more about what we are doing, here is a selection of papers, other papers behind the one presented here that can provide you with more information. Thanks a lot for listening.
 I'm delighted to take part in ICMS 2020, and especially so because I have the occasion  to tell you more about software heritage and how you can use it to archive and reference  all the source code in the world.  The reason why we want to do this is that software source code is knowledge and not  any kind of knowledge, a very special kind of knowledge because it is written by humans,  for humans to read, and also sufficiently technically detailed to be executable by  machine.  This is not a new observation when I was a student, I was reading a book by Yarrow  Davenson, and in the introduction I found this beautiful phrase, I mean, programs must  be written for people to read, and only incidentally for machines to execute.  I mean, back then there was not much source code available, so this could just seem a  phrase you say to your students, tell them they need to turn in your homework, your  CS class in a readable way, otherwise they will get bad grades, but it's much deeper  than that.  The point is that when you write a piece of software you know it with a ball, you might  have errors, you need to reuse it, modify it, adapt it, and so you need to be able to  read it later on.  Today, 30 years later, we have access to an incredible amount of open source code, and  so we can find jewels like this excerpt of the Apollo 11 guidance computer source code,  which was used to control the Apollo mission, or this particularly amusing function that  computes one over a square root of X for floating numbers, but without using any floating point  co-processor at all.  As then Schuster, the board director of the Computer History Museum, used to write a few  years ago, but actually source code, it opens up a view in the mind of the designers.  Well, but when we now focus on research, our day-to-day activity, it's easy to see that  software source code is one of the three key pillars of open science.  We tend to think a lot about articles, they are super important, about data, we need data  to be able to do our computation evaluations, but for too long software has been forgotten,  and software is essential to understand what kind of transformation you're actually doing.  Well, once we notice that we have open science, we need these three pillars, and that we need  to focus on building the missing one, which is the one for software source code, in particular  open source one, then we discover that we need to cater to a plurality of needs, depending  on the different kind of actors in research.  One kind of actor researcher, you, me here, we just want to be able to find a place where  we can safely archive the software used in our articles, and find a way to provide precise  references to the software we archive, so our readers or ourselves can get back to the  exact version we used.  We need to be able to look at the software, find useful, we need to get credit for what  we do, we want to be able to tinker with the software others to adapt it to improve it.  But then other actors, like collaborators or team, they need to track the software contribution,  you know, as usually, at least to have a web page, more than often to produce reports,  and if you go up in the hierarchy, you will find top-level research organization, ministry  research, etc., and they want to know what kind of software assets they are contributing  to.  Well, if you think a little bit carefully to address all these needs, there are at least  four different things we need to do, and I will try to present them to you in what I  believe is the real order of difficulty.  First of all, we need a place where to archive software.  It is a place where you put something and you can find it again.  I mean, this is essential for reproducibility, if you cannot find the software for your paper,  what can you do?  Then a little bit more difficult, actually, you need to have proper identification.  I pretend this is more difficult than just archiving because putting a zip file somewhere  is very easy to do, but if you just use a URL to link to it, well, reproducibility is  not actually really guaranteed.  Then you need to have proper metadata for this cramming software.  It is more complex than the previous levels because there are too many ontologies out  there.  Finally, you need to get credit, citation, this is important for the evaluation, etc.  This is a more touchy subject because we need to decide who is the author, who is not,  who did what, etc.  So it's more political or human level, so less technical, more complex to do it properly.  Well, to address all these things in a proper way, we need an infrastructure which is actually  designed for software.  Well, the good news is, now we have one.  At least for addressing the first two issues I take here, archival and identification.  So let me introduce you to software heritage.  Software heritage is an initiative which was started over five years ago with a clear mission  to go out, collect, or the source code of all software publicly available, preserve  it and make it available to everybody.  If you want to have an idea of how to think about software heritage at a very high level,  first of all it is a reference catalog.  Today we have a source code available from so many different platforms, I mean code hosting  platform like Github, Distribution, like Debian or many, many other places.  And we need a central place where we have a catalog of everything that exists.  We are building this.  The other thing which is important is that we are building an archive.  Unfortunately, for quite a long time we kind of misunderstood the development platform for  archives.  The development platform is not an archive.  It's a place where I go, I create a project, work with others to improve it.  Sometimes I can rename it, remove it, move it elsewhere so there is no guarantee that  what I can find here today, I will find it tomorrow.  An archive was surely missing.  We are building it.  And finally, we are also starting to build an infrastructure that allows to research  on the global scale or not the source code which is available because we collect it,  we archive it in a uniform way.  So it's also an incredible data set for doing research.  Well, how will you do to go out, collect, preserve and share all the source code all  the work?  Let me give you a brief overview of what we are doing.  What we are building is a system that goes out and actually harvest source code from  all different platforms that we can discover and that we can connect to.  This is not an easy task because it is not like an archive in the web.  We do not have a standard for communicating for crossing or distribution platform.  So talking to GitHub is not the same as talking to Merkurial or sorry, to be bucket or to  GitHub, etc.  And so we need to build that after one at a time.  Once we do this, we can get a list of tons and tons of different software projects, maintaining  using different version control system, different package formats, etc.  And since we are here for the long run, we do not stop there.  We just don't make a scene, a copy of what we found out there.  We go the extra mile and actually convert all the different version control system,  all the different package formats, all the information we can get out there into a single  universal data format, which is basically a gigantic Merkel-Direct Secret Graph.  Today, we have already archived more than 8 billion unique source files for more than  130 million software origins.  And I would like to spend a little bit of time on the peculiarity of this Merkel Graph.  You have to know that all the nodes in the graph here represent either file contents  or directories or revisions or commits, releases, etc.  And to each of these nodes, we associate a unique identifier, which is computed from  the object itself through cryptographic functions.  And these are the software heritage identifiers or suites.  The general scheme of a software heritage identifier is like this.  You have a prefix, SWH, which is registered with the IRNAT today.  The schema version, up to now we are using version 1, a tag that tells you what is the  object that is defined here, and then the identifier, which is the hash, the cryptography  hash.  As kind of object, we have contents, directories, revisions, releases, or snapshots.  You can also add some extra qualifiers that allow you to describe to the reader or the  user of this identifier where you find the software from, in which position, inside the  graph, what are the lines which you are interested in, and so on.  This is becoming a standard in industry.  I mean, now it is part of the Dinos Foundation SPDX definition.  You can find it also in WikiData, and you can click on these links to see some examples  if you're interested, but we'll demo it right away.  Now why software heritage is special for research software in particular?  First of all, it is a universal archive.  This means it collects really all software, not just academic software.  So if your research software actually depends on external libraries, chances are we are collecting  them.  The other point is that we are actually proactively harvesting codes.  So we do it without waiting for somebody depositing it in.  And that's the reason why we have so many project archive right now.  All this means that probably some of your software may be there already.  You could check right now.  If it is not, you can actually save it now in that position.  The other important point is that we provide identifier.  This screen I have briefly shown to you, and we see it in the demo right away.  They are intrinsic.  They do not depend on any kind of register.  So decentralized, cryptographically strong.  You can verify that what you download or what you find that has this identified is actually  the same software that was mentioned in an article, the reference it.  You can use them to enhance articles for better reproducibility.  And also more recently released a Biblatex style that allows you actually to cite software  properly in your papers with pointers to software usage suites.  Their detailed guidelines are in the paper and also available online.  And now I think the moment I scan to stop talking and start doing, so let's start to  look at a little bit of a demo of how we can use all this.  To see how using software heritage can improve the way we write articles or research articles  that are mentioned or include software, well, let's try to have a look at what I actually  did a few years ago.  Here is the list of my publications.  If you look in 2012, here is an article that I wrote with a friend about a particularly  interesting implementation of MapReduce.  Here is a local copy of the paper.  Let me put it full screen.  So it is 2012.  Typical paper in functional programming and parallel programming, a little bit of mathematical  description of the operation you want to perform.  Then we go down to the implementation section here.  We actually found a way to implement this processing schema, a particularly nifty way.  We're very proud of it.  That's the reason why we actually go through the lines of code, stepping one by one and  telling the reader why this is doing any job in a proper way.  Here is a copy of the key algorithm that ImplementSmapReduce uses in some very nifty trick with  a Unix memory mapping system.  Well, okay.  So 29 lines.  We are proud of it.  We describe it.  Then we do some tests to show the data actually scales up, etc.  That's fantastic.  But then if you want to play with this software and use it and check that what we say was  correct, how can you do it?  Already back then into 2012, I was very fond of being open access, open source, open data,  etc.  So at the end of the article you see, we say that the full source code of the library is  available under a free software license, LGPL, from a development platform.  Back then I was mistaking developing platform for archives.  And it was also incorporated in a Gordy installation system for the OCaml programming language.  When unfortunately three years later, Gitorios was shut down.  So there is no point in clicking here.  You will find nothing.  And also unfortunately, the Gordy installation system has gone away.  We've got another one called Open, to which I contributed.  So you find this paper, you read it, you get excited about a particular implementation  of the algorithm and there are nothing you can, despite all my good will to try to do  my best, the best that was available a few years ago.  Well, today things have changed quite a bit.  You see, for example, here, this is the same paper.  The only difference you see now is that in 2020 I had taken exactly the same latex source  of this paper and have made some minor modification using what is available today with software  access.  So one minor modification is that just below the source code, which is the snippet of source  code which is shown in the paper.  Now I added this little phrase with a pointer to actually the suite of the software identifier  for the source code that corresponds to what is shown here.  Look at it.  You see there is a resolver part, archive.sortware.org, and then followed by this from the suite  with all the extra qualifiers that allow to put it in context.  If I click here, what happens when I am brought exactly, exactly in the software architecture  archive in front of the exact code fragment that is mentioned in the article with all  the necessary contextual information.  So you see here is a commit where it is located, this file, the path inside the commit so you  may know the name of the file, etc.  And actually if you look at this you will see that well the code in the paper does not  really perfectly match what you see in the archive.  Let me put it a little smaller here.  Here are 29 lines and here are a bit more than 29 lines.  But actually the point is that to fit into the page element we had to remove some lines  and we just removed some exception.  And we did really change the overall function of the algorithm that you see if you try to  reproduce it's not the same.  So it's much better to have a link there.  And the other modification we made is at the end of the article where we were mentioning  the full version control system on GitTorios which is now gone.  We also added a link to the archived copy on software heritage which allows us to get  to the latest status of the archived copy on the software edge of this particular repository.  Here we have all the history available, all the commits of the version etc. which are  available for you.  So that's great.  It's really a game changer for what we plan to do with the research software today.  And it's not all because you can also actually cite the software today.  You will see in the paper we can use this new bibliotech style to describe the software  in this Parma library.  The particular version, the version we used in the paper, the particular snippet that  corresponds to it, I mean this is actually what you have seen in the presentation a few  minutes ago.  And you can find them in the bibliography properly highlighted as software release or  software excerpt, I think, with the suites which are also perfectly clickable.  And I hope you like this demo.  In any case, in the slides that you can download online, you will have pointers to the things  we have seen and also to a lot more material I do not have time to show you today.  And time to go to the conclusion.  I would like to say, first of all, I mean software is really an open universal initiative.  We really try to make it clear how international, independent, non-profit, long term initiative  it is.  That is the reason why we have partnership with UNESCO.  On the other side, all this work has been started thanks to INRIA support, which was  fundamental to start the effort five years ago.  And now we are bringing together many different sponsors and partners.  So you see there is a lot of space here, there is space for more to come people to come.  I hope to have convinced you the software is special.  It's a universal archive.  It provides intrinsic identifiers.  It's open, non-profit, long term.  It's an infrastructure for open science.  And then you can help.  Use software heritage in your article, in your conference, in your journals, in your proceedings.  See what the people in SSWMART or IPOL are already doing.  Do the same in other conferences.  If you find software which is not saved already, please do trigger the archive of the software  in our archive.  You can contribute to software heritage.  Everything is open source.  Just spread the word.  Tell other people about what is going on.  When I will stop here, if you want to learn more about what we are doing, here is a selection  of papers, other papers behind the one presented here that can provide you with more information.  Thanks a lot for listening.
2020-07-15-ICMS_0_47.png 2020-07-15-ICMS_48_251.png 2020-07-15-ICMS_252_3371.png 2020-07-15-ICMS_3372_18335.png 2020-07-15-ICMS_18336_18851.png 2020-07-15-ICMS_18852_18923.png 2020-07-15-ICMS_18924_18971.png 2020-07-15-ICMS_18972_19103.png 2020-07-15-ICMS_19104_19151.png 2020-07-15-ICMS_19152_19451.png 2020-07-15-ICMS_19452_19511.png 2020-07-15-ICMS_19512_19643.png 2020-07-15-ICMS_19644_19775.png 2020-07-15-ICMS_19776_20351.png 2020-07-15-ICMS_20352_20495.png 2020-07-15-ICMS_20496_20615.png 2020-07-15-ICMS_20616_21539.png 2020-07-15-ICMS_21540_22835.png 2020-07-15-ICMS_22836_23051.png 2020-07-15-ICMS_23052_23699.png 2020-07-15-ICMS_23700_23747.png 2020-07-15-ICMS_23748_23951.png 2020-07-15-ICMS_23952_24455.png 2020-07-15-ICMS_24456_24527.png 2020-07-15-ICMS_24528_25691.png 2020-07-15-ICMS_25692_25739.png 2020-07-15-ICMS_25740_30248.png