##

• L’archivage des logiciels : une des conditions de la reproductibilité scientifique
• L’accès au code source des logiciels
  • Définitions : code source, exécutable, compilation
  • Ce que nous apprend le code source : illustration
• Software Heritage, une infrastructure spécialisée dans l’archivage du code source
  • Les options d’archivage
  • Les fonds de Software Heritage
• Rendre les logiciels identifiables
  • Les besoins d’identification spécifiques au logiciel
  • Pourquoi citer les logiciels
  • Utiliser des identifiants pérennes adaptés
  • Obtenir et utiliser un SoftWare Hash Identifier (SWHID)
  • Quel identifiant pour quel besoin ?
• En pratique : trouver et référencer des logiciels archivés
  • Naviguer et rechercher des logiciels sur Software Heritage
    • Cas d’étude quand vous explorez Software Heritage
      • Option 1. Vous ne connaissez que le nom du projet
      • Option 2. Vous possédez un fichier du code source
      • Option 3. Vous connaissez un extrait du code
      • Option 4. Vous connaissez l’adresse du dépôt de référence d’un projet
      • Option 5. Vous connaissez un code de hachage
      • Option 6. Vous possédez un identifiant SoftWare Hash Identifier (SWHID)
    • Exercice : mettre en œuvre sa stratégie de recherche
  • Choisir l’identifiant pérenne à intégrer dans une citation
• Archiver du code source
  • Dans quels cas archiver manuellement du code source
  • Vérifier que la version archivée d’un dépôt est à jour
  • En pratique : archiver du code source que vous avez écrit
    • Créer un dépôt GitLab
    • Écrire une portion de code
    • Ajouter une licence
    • Déclencher l’archivage du dépôt
• Pour aller plus loin : décrire un logiciel avec CodeMeta
  • Ajouter des métadonnées pour rendre son logiciel identifiable
  • CodeMeta, la pierre de Rosette des auteurs de logiciels
  • En pratique : utilisation de CodeMeta Generator pour documenter votre dépôt
• Conclusion
• Avez-vous plus de questions ?
• Remerciements
• Notes de fin

L’archivage des logiciels : une des conditions de la reproductibilité scientifique

Une recherche reproductible est une recherche plus robuste et plus transparente. Or il existe plusieurs formes de reproductibilité : ainsi, dans certaines disciplines, ce qui compte est davantage de pouvoir reproduire la méthode que d’obtenir les mêmes résultats. Dans cette leçon, l’accent est mis sur la reproductibilité computationnelle : la capacité à retrouver les mêmes résultats en utilisant les mêmes méthodes et les mêmes outils que l’auteur initial.

Si l’archivage et l’ouverture des données de recherche sont de plus en plus répandus au sein de nombreuses communautés académiques, ces pratiques ne répondent que partiellement à la question de la reproductibilité des travaux scientifiques. En effet, ainsi que le soulignent Davenport et ses co-auteurs, comment comprendre ou reproduire des résultats sans accéder également au logiciel qui a permis de traiter les données ?

« A common theme is a growing emphasis on “reproducibility” being discussed in many disciplines […]. This goes beyond “data” and requires software and analysis pipelines to be published in a usable state alongside papers¹. »

Archiver les logiciels est donc un prérequis pour garantir un accès partagé aux auteurs, contributeurs, utilisateurs et lecteurs de logiciels².

Quoique essentiel à la compréhension des résultats, le logiciel n’est pourtant pas toujours identifié comme une ressource à préserver ; faute de réel archivage, maint renvoi pointe vers des sources déplacées ou perdues. Un article de D. Spinellis³ fournit ainsi des éclairages sur la courte durée de vie des URL dans les articles publiés (plus qu’un hamster mais moins qu’un pingouin). Le site web d’un individu ou même d’un laboratoire n’offre aucune garantie de pérennité : un simple changement de fournisseur d’accès à Internet, un départ à la retraite, le changement de nom d’une institution peuvent suffire à rendre tous les liens obsolètes.

Même les « forges⁴ », plateformes de développement collaboratif en ligne telles que GitHub et GitLab — dont l’usage s’est très fortement accru ces dernières années, y compris dans le monde académique⁵ — n’offrent pas de garantie d’accès pérenne. Leurs conditions d’utilisation peuvent être modifiées et les espaces de travail fonctionnant avec une technologie donnée ne seraient alors plus maintenus. Pire encore, ces plateformes peuvent être intégralement désactivées, coupant même aux auteurs de logiciels tout accès à leur contenu — mésaventure qu’ont connue les utilisateurs de Google Code. Même les forges institutionnelles offrant de plus grandes garanties en termes de services peuvent être désactivées. Les forges sont donc de puissants outils de collaboration mais ne constituent pas la solution optimale pour mettre du code informatique à disposition des lecteurs d’un article académique. Elles facilitent l’écriture du code, non sa préservation.

L’absence de recours à de vraies solutions d’archivage, tant pour les développeurs que pour les utilisateurs de logiciel, a donc des conséquences en chaîne sur tout le système de citation académique et la reproductibilité des travaux — autrement dit, en définitive, sur la qualité de la science. Aussi est-il crucial de disposer d’un archivage dans un entrepôt dédié.

L’accès au code source des logiciels

Sous quelle forme les logiciels doivent-ils être archivés ? Leur conception traverse en effet trois phases : le code source, la compilation, l’exécutable. Définissons d’abord ces termes.

Définitions : code source, exécutable, compilation

Le développement d’un logiciel commence par l’écriture d’un « code source », c’est-à-dire d’une série d’instructions écrites dans un ou plusieurs langages informatiques (par exemple Python, R, etc.), lisibles et compréhensibles par des humains. Il s’agit donc d’une représentation textuelle de l’architecture du programme et des algorithmes qui en sous-tendent le fonctionnement.

À l’autre bout de la chaîne, un « exécutable » désigne la version transformée du code source pour la rendre lisible par la machine. Cette traduction pour la machine – non lisible par les humains – prend la forme d’une série de 0 et de 1 (d’où le nom de « binaire » parfois donné comme synonyme d’« exécutable »), codant les impulsions électriques nécessaires à l’exécution du programme.

La « compilation » est le processus transformant le code source écrit par des humains en un programme exécutable pour la machine. On peut donc imaginer le code source comme une recette de cuisine, l’exécutable comme le plat obtenu en suivant la recette, et la compilation comme le travail culinaire.

L’archive Software Heritage, qui sera présentée ultérieurement, ne collecte pas d’exécutables, mais le code source correspondant car il constitue le composant du logiciel exploitable sur le long terme. En effet, la compilation n’est pas un processus aisément réversible : si l’on peut immédiatement passer du code source à l’exécutable, l’inverse est beaucoup plus délicat et incertain — de même qu’il ne suffit généralement pas de goûter un plat pour connaître sa recette. De plus, le code source d’un logiciel, comme une recette de cuisine, peut être inspecté, compris, éventuellement modifié et à nouveau transmis par ses utilisateurs.

Autrement dit, renvoyer vers le code source constitue la manière la plus sûre et efficace de partager du logiciel sur le long terme.

Ce que nous apprend le code source : illustration

Illustrons le fait que le code source nous donne strictement plus d’informations que le code exécutable.

Observons par exemple un fragment de code de la mission Apollo. On voit que parallèlement au code « efficace », voué à dicter le comportement la machine, se trouvent en fin de ligne, derrière les croisillons (#), des informations destinées au lectorat humain. Ces commentaires fournissent la « raison d’être » du code destiné à la machine : les auteurs y expliquent pourquoi ils ont jugé pertinent d’ajouter telle ou telle ligne de code. Cela permet de s’orienter rapidement dans le code, d’identifier les lignes responsables d’un certain comportement et éventuellement de les modifier.

À la compilation, les commentaires sont purement et simplement supprimés. De ce fait, si un humain essayait de lire le code exécutable, il n’aurait pas accès à ces précieuses informations.

Software Heritage, une infrastructure spécialisée dans l’archivage du code source

Software Heritage, infrastructure portée par l’Inria et l’Unesco, est dédiée à l’archivage du « patrimoine logiciel mondial de l’humanité ». Les trois missions de Software Heritage sont la collecte, la préservation et le partage du code des logiciels rendus publics. Pour les raisons exposées dans la section précédente, Software Heritage conserve le code source des logiciels, c’est-à-dire la partie du logiciel compréhensible par l’être humain⁶.

Le premier avantage de Software Heritage est de fournir un point d’entrée central vers des millions de logiciels, développés et disséminés dans une multitude de plateformes. Le second bénéfice pour l’utilisateur est d’accéder à des collections régulièrement mises à jour de manière automatisée. Ainsi, la personne voulant renvoyer vers une version donnée d’un logiciel a le choix parmi les différentes versions archivées. De plus, la personne qui a développé un logiciel peut compter sur une version archivée de son travail.

Les options d’archivage

Software Heritage fournit plusieurs options pour l’archivage des logiciels :

1. Un archivage automatisé : les contenus publics des forges les plus couramment utilisées sont archivés automatiquement, à échéance régulière ; la liste des forges dont le contenu est périodiquement « moissonné » inclut toutes les forges les plus populaires. La plupart des logiciels open source que vous utilisez sont donc très probablement déjà archivés dans Software Heritage.

2. Un archivage manuel : il est aussi possible d’archiver un logiciel ou de mettre à jour son archivage manuellement. En effet, ce service permet de résoudre la question de la mise à jour des contenus entre deux vagues d’archivage automatisé. Cette fonctionnalité est utilisable sans créer de compte, et il n’est pas nécessaire d’être l’auteur du logiciel pour y recourir. En revanche, si le logiciel n’est pas public, son archivage est bloqué. La documentation présente les différentes options.

La pérennité de l’accès aux logiciels archivés est garantie par des identifiants spécialisés, les SoftWare Hash Identifiers (SWHID), que nous découvrirons de manière plus détaillée dans les sections suivantes. À la différence d’un identifiant généraliste tel que le DOI, le SWHID est dédié au logiciel. Ainsi, le SWHID permet non seulement de renvoyer vers une version donnée, mais aussi vers différents composants du logiciel plutôt qu’au programme dans son ensemble. Un SWHID s’obtient instantanément et gratuitement dès lors que le logiciel est archivé dans Software Heritage.

Les fonds de Software Heritage

Software Heritage permet un accès unifié à des fonds issus d’une grande diversité de gisements. Outre les plateformes de développement et de distribution les plus communément utilisées, Software Heritage fournit aussi :

• Des contenus publics de forges désactivées comme Google Code.
• Des contenus des forges institutionnelles basées sur GitLab (par exemple l’instance GitLab de l’IN2P3 du CNRS) ayant fait la demande d’être versées dans l’archive.
• Des codes sources associés à des articles, grâce à ses partenariats avec des revues en sciences et technologies.
• Des codes sources de logiciels déposés dans l’archive ouverte nationale HAL. Le dépôt dans HAL permet de créer une description citable du logiciel alors que l’archivage dans Software Heritage est principalement dédié à rendre identifiable des composants techniques du logiciel (voir le chapitre de la leçon sur les identifiants pérennes). Multidisciplinaire, HAL permet de partager en libre accès les résultats de recherche, publiés ou non.

La politique documentaire de Software Heritage s’applique à l’échelle d’un gisement d’informations (forge, plateforme) et non pas logiciel par logiciel. L’enjeu est d’offrir la couverture la plus large possible. Cet objectif est motivé par la nature composite du logiciel : un logiciel de recherche peut ainsi s’appuyer sur des éléments issus de communautés de l’administration publique ou de l’industrie. C’est pourquoi les fonds de Software Heritage excèdent le périmètre académique.

En outre, la plus-value de Software Heritage est de préserver l’historique de développement des logiciels issus des forges, en plus du code source. L’historique de développement documente la genèse d’un logiciel et peut fournir des explications sur son fonctionnement. Voici l’exemple d’une révision (commit) de 2008 rédigée par Matthew Wilcox :

« Generic semaphore implementation
Semaphores are no longer performance-critical, so a generic C implementation is better for maintainability, debuggability and extensibility. Thanks to Peter Zijlstra for fixing the lockdep warning. Thanks to Harvey Harrison for pointing out that the unlikely() was unnecessary.
Signed-off-by: Matthew Wilcox willy@linux.intel.com
Acked-by: Ingo Molnar mingo@elte.hu »

Lorsqu’un code source est développé dans une forge, chaque modification peut être documentée à l’aide d’une “révision” (commit). L’ensemble des révisions permettent de reconstituer l’historique des changements apportés. Dans l’exemple ci-dessus, Matthew Wilcox justifie sa démarche visant à simplifier une partie du noyau Linux en remplaçant 7679 lignes complexes par 314 lignes élémentaires dans 113 fichiers. La révision incarne l’unité intellectuelle qui sous-tend toute cette diversité de modifications ponctuelles. Un historique de développement peut ainsi fournir des informations contextuelles précieuses pour comprendre la structure d’un logiciel.

Enfin, si le code source d’un logiciel est supprimé de son emplacement d’origine, cela n’a pas d’impact sur les fonds de Software Heritage. Les évolutions du code source sont archivées mais si la ressource est supprimée, ce changement n’est pas répercuté, ce qui prémunit du risque de lien brisé.

Rendre les logiciels identifiables

Les logiciels constituent des ressources particulièrement difficiles à identifier sur le long terme. Comment surmonter ces difficultés ?

Les besoins d’identification spécifiques au logiciel

Pourquoi est-il si difficile d’identifier un logiciel ? Certaines raisons sont contextuelles :

• la liste ou le rôle des contributeurs d’un logiciel peut évoluer : une personne qui faisait partie des auteurs principaux de la version 1 peut devenir un testeur de la version 2 ;
• les logiciels peuvent changer de noms comme de plateforme de développement. Les articles contenant des liens vers des forges ou des sites web classiques sont alors des liens brisés.

D’autres raisons sont inhérentes à la nature même du logiciel :

• les logiciels connaissent des montées de versions mineures comme majeures, et on peut souhaiter citer une version, voire une étape précise du développement d’une version ;
• les logiciels, même simples en apparence, font intervenir de nombreux composants et leur architecture peut être complexe. Autrement dit, on peut avoir besoin de faire référence uniquement à un élément du logiciel et pas au produit dans son intégralité.

Ainsi, l’archivage des logiciels est une tâche fondamentalement différente de l’archivage de jeux de données. Les données associées à un article ou un projet scientifique sont généralement dans un état « figé », unique et définitif, dont il suffit d’assurer la disponibilité de long terme, à l’aide d’un entrepôt dédié et d’un identifiant de type DOI. Inversement, le code source est un contenu fortement évolutif : il convient donc de garder la trace de toutes les versions mises à disposition du public. De plus, chaque production de code informatique, y compris dans le cas des scripts les plus simples, possède généralement une structure sous-jacente très complexe : aucun extrait de code ne peut exister en dehors d’un environnement d’exécution élaboré, devant donc à son tour être archivé et versionné. La nature fondamentalement évolutive et modulaire des logiciels appelle donc des solutions spécifiques en termes d’archivage et d’identification.

Pourquoi citer les logiciels

Citer un logiciel s’avère nécessaire lorsque celui-ci a joué un rôle déterminant dans la réalisation des travaux de recherche. La question suivante peut servir de repère : dans quelle mesure le logiciel a-t-il un impact direct sur les résultats obtenus ? S’il n’est pas pertinent de citer un outil de traitement de texte, il est par exemple judicieux de citer le logiciel de reconnaissance optique de caractères utilisé. Il est courant de voir cité un article décrivant le logiciel plutôt que le logiciel lui-même. Or, cette pratique n’est pas la plus adaptée car elle ne permet pas d’identifier facilement et avec certitude le logiciel en question, ainsi que le démontre M. Jackson :

« The authors had cited an OGSA-DAI paper that should have meant they were using a version of the software between OGSA-DAI 1 and 6. Later in their paper, the authors mentioned a component that was specific to OGSA-DAI versions 2.5 to 6. However, the authors then talked of another component and a toolkit, which was only available with a completely different version of the software. Without my highly detailed knowledge of the OGSA-DAI project, it would have been impossible to determine what software was used⁷. »

Par ailleurs, il n’existe pas toujours d’article associé au logiciel : il peut avoir été développé en dehors d’une communauté académique, ou simplement, n’avoir jamais été présenté dans une revue. Cela renforce donc le besoin de citer le logiciel lui-même, au même titre qu’une autre ressource académique. Les pratiques de citation de logiciels ne sont pas encore très codifiées dans les communautés académiques. Il n’existe pas de standard descriptif. Sur la base de recommandations d’experts, voici une proposition de noyau minimal d’informations à mentionner⁸:

• le nom du logiciel de la manière la plus précise possible (par exemple le nom du package) ;
• la date de mise à disposition de la version ou, à défaut, la date d’utilisation du logiciel par l’utilisateur à l’instar de ce qui se pratique pour les citations de pages web ;
• l’auteur du logiciel ;
• la localisation initiale (par exemple le lien vers la plateforme de développement) ;
• l’identifiant pérenne (par exemple le SWHID).

Les utilisateurs de LaTeX peuvent utiliser le biblatex-software package pour faciliter la tâche.

Utiliser des identifiants pérennes adaptés

Les identifiants pérennes sont un moyen d’assurer un accès stable à une ressource, par exemple un document en ligne ou une description de document. Ils permettent d’établir des liens entre des informations de différentes natures : on sait par exemple qu’un article donné, identifié par un DOI, a été rédigé par telle personne, identifiée à son tour par sa référence ORCID (Open Researcher or Contributor ID). Et cette personne exerce dans une institution elle-même identifiée via le Research Organization Registry (ROR).

Le Comité pour la science ouverte définit ainsi un identifiant pérenne :

« Numéro ou une étiquette alphanumérique, opaque ou explicite, lisible par des machines et par des humains, permettant de désigner et de retrouver de manière univoque et pérenne un objet, un document, une personne, un lieu, un organisme, ou toute entité, dans le monde réel et sur internet⁹. »

Les identifiants réduisent les ambiguïtés : il peut en effet parfois être difficile de savoir si tel auteur ayant publié dans une discipline donnée est l’homonyme d’un autre auteur publiant dans un domaine proche, ou s’il s’agit d’une seule personne active dans plusieurs champs. On peut également citer le cas des institutions, dont le nom peut changer au fil du temps. Plusieurs institutions peuvent fusionner et former une nouvelle entité à décrire. Ces changements rendent difficiles l’identification des ressources produites par ces instances.

On peut également noter que les objets académiques à identifier se sont diversifiés et le logiciel fait partie des ressources vers lesquelles il est nécessaire de créer des liens valables sur le long terme.

Obtenir et utiliser un SoftWare Hash Identifier (SWHID)

Comme nous l’avons vu précédemment, même si le DOI est l’identifiant le plus connu et le plus utilisé dans le monde académique, il n’est pas le plus adapté à l’identification des logiciels : on n’a généralement pas de DOI associé à chaque composant du logiciel — encore moins à chaque étape fine de son processus de développement.

Le SoftWare Hash Identifier permet de pointer vers différents composants du logiciel, ainsi que vers des actions de son historique de développement. Il en existe cinq types différents en fonction de la façon dont on souhaite faire référence à un logiciel donné. La documentation technique détaille les types de SWHIDs disponibles. En voici une synthèse :

Quel identifiant pour quel besoin ?

Le tableau suivant résume les informations présentées dans cette section.

Ces différents identifiants sont complémentaires car ils répondent à des besoins différents. Ainsi, un HAL-ID renvoie vers une description de logiciel incluant un SWHID chargé de pointer vers un contenu donné. Si l’on souhaite renvoyer vers un fichier précis, il faut recourir au SWHID.

En pratique : trouver et référencer des logiciels archivés

Dans cette section, nous voyons comment trouver dans l’archive Software Heritage les logiciels que vous utilisez et comment obtenir les identifiants dont vous avez besoin pour les citer correctement dans vos productions académiques. Référencer un logiciel signifie lui attribuer un identifiant pérenne.

Naviguer et rechercher des logiciels sur Software Heritage

Pour consulter ou citer du code source sur Software Heritage, il faut déjà l’avoir trouvé dans l’archive. Mais comment s’orienter dans une archive aussi foisonnante ? Selon le degré d’information que vous possédez sur la ressource recherchée, vous vous trouverez dans l’une des situations suivantes :

1. Vous ne connaissez que le nom du projet, par exemple « Linux ».
2. Vous possédez un fichier du code source, par exemple le texte de la GNU General Public License v3.
3. Utilisateur avancé, vous connaissez un extrait du code, par exemple unsigned three = 1;.
4. Vous connaissez l’adresse du dépôt de référence du projet, par exemple https://github.com/torvalds/linux.
5. Utilisateur avancé, vous possédez un code de hachage permettant d’identifier un certain fichier, un répertoire, une version ou une révision.
6. Vous possédez un SoftWare Hash Identifier (SWHID).

Cas d’étude quand vous explorez Software Heritage

Examinons chacun des cas présents, en allant du point de départ le plus imprécis vers le plus précis. Les options 1, 2, 4 et 6 permettent une interrogation facilitée de Software Heritage (Fig. 1).

Option 1. Vous ne connaissez que le nom du projet

Par exemple pour le projet « Linux », le plus simple est de chercher son dépôt officiel dans un moteur de recherche ou un catalogue de logiciels, par exemple le catalogue des logiciels du MédiaLab de SciencesPo). En tapant « Linux source code » dans un moteur de recherche, vous tomberez assez rapidement sur une page intitulée « GitHub - torvalds/linux: Linux kernel source tree » à l’adresse https://github.com/torvalds/linux. Cette adresse est celle de l’« origine », c’est-à-dire du dépôt distant de référence. Elle permet de retrouver très facilement le code source sur Software Heritage, comme vous le verrez dans le point 4 ci-dessous.

Option 2. Vous possédez un fichier du code source

Par exemple pour le texte de la GNU Public Licence v3, rendez-vous à l’adresse https://www.softwareheritage.org/. Glissez et déposez votre fichier dans l’encadré intitulé « Vérifiez si le code source qui vous intéresse est déjà présent dans l’archive », puis cliquez sur « Search ». Un menu déroulant vous indiquera alors si le code figure sur Software Heritage et quel est son code de hachage, par exemple 8624bcdae55baeef00cd11d5dfcfa60f68710a02. Cliquer sur « Browse » vous permettra de visualiser ce fichier à l’adresse https://archive.softwareheritage.org/browse/content/8624bcdae55baeef00cd11d5dfcfa60f68710a02/?path=GPL-3.

Option 3. Vous connaissez un extrait du code

Considérons par exemple l’extrait unsigned three = 1;. Vous pouvez chercher davantage d’informations à son sujet à l’aide d’un moteur de recherche. Jonglez avec les guillemets pour cibler l’expression exacte (comme lorsque vous effectuez une recherche dans un catalogue ou un moteur de recherche, ajouter des guillemets permet de faire porter la recherche sur l’expression telle que formulée), et ajoutez des mots-clefs pour affiner les résultats. En tapant par exemple « “unsigned three = 1” source code », vous trouverez rapidement un lien vers la page https://github.com/torvalds/linux/blob/master/fs/ext4/resize.c, ce qui vous indique l’adresse d’origine du projet et vous conduit une fois de plus à la situation décrite dans le point 4 ci-dessous.

Option 4. Vous connaissez l’adresse du dépôt de référence d’un projet

Si vous connaissez par exemple l’adresse https://github.com/torvalds/linux du projet Linux, il suffit de la saisir dans la barre de recherche de Software Heritage. Vous serez alors automatiquement redirigé vers la page correspondante de l’archive, qui vous permettra de naviguer dans le code source de Linux. Vous pouvez par exemple explorer le fichier fs/ext4/resize.c jusqu’à trouver la ligne contenant l’instruction paradoxale unsigned three = 1; ;

Option 5. Vous connaissez un code de hachage

Vous êtes un utilisateur suffisamment expérimenté et possédez le code de hachage (SHA-1) permettant d’identifier un certain fichier, un répertoire, une version ou une révision. Par exemple, en visitant l’adresse https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=64ac24e738823161693bf791f87adc802cf529ff, vous avez trouvé le numéro de révision (commit) 64ac24e738823161693bf791f87adc802cf529ff, ou bien vous savez que le code de hachage d’un fichier est 8624bcdae55baeef00cd11d5dfcfa60f68710a02. Vous pouvez alors explorer la page correspondante en rajoutant l’un des préfixes suivants, selon le type de la ressource :

* pour un fichier&nbsp;: <https://archive.softwareheritage.org/browse/content/> ;
* pour un répertoire&nbsp;: <https://archive.softwareheritage.org/browse/directory/> ;     
* pour une capture&nbsp;: <https://archive.softwareheritage.org/browse/snapshot/> ;    
* pour une version&nbsp;: <https://archive.softwareheritage.org/browse/release/> ;    
* pour une révision&nbsp;: <https://archive.softwareheritage.org/browse/revision/>.

On trouvera donc la révision 64ac24e738823161693bf791f87adc802cf529ff à l’adresse https://archive.softwareheritage.org/browse/revision/64ac24e738823161693bf791f87adc802cf529ff, et le fichier dont le code est 8624bcdae55baeef00cd11d5dfcfa60f68710a02 à l’adresse https://archive.softwareheritage.org/browse/content/8624bcdae55baeef00cd11d5dfcfa60f68710a02. Vous pouvez également, pour chacun de ces types de ressources — à l’exception notable des fichiers —, obtenir un SoftWare Hash Identifier (SWHID) en ajoutant le préfixe correspondant :

* `swh:1:dir:` pour un répertoire ;    
* `swh:1:snp:` pour une capture ;    
* `swh:1:rel:` pour une version ;    
* `swh:1:rev:` pour une révision.

Vous vous trouverez alors dans la situation abordée dans le point 6 ci-dessous.

Option 6. Vous possédez un identifiant SoftWare Hash Identifier (SWHID)

Vous pouvez alors le taper dans la barre de recherche de l’archive. Par exemple, si vous y saisissez l’identifiant swh:1:dir:1fee702c7e6d14395bbf5ac3598e73bcbf97b030, vous serez redirigé vers la page https://archive.softwareheritage.org/browse/directory/1fee702c7e6d14395bbf5ac3598e73bcbf97b030/.

À noter : le recours aux catalogues de logiciels reste une pratique peu répandue, y compris parmi les développeurs. Pourtant, ces outils spécialisés permettent des recherches plus ciblées que les moteurs généralistes. Vous connaissez les institutions dont les domaines d’expertise sont proches des vôtres : vérifiez s’il n’existe pas un catalogue recensant la production logicielle de cet établissement. Votre propre institution a peut-être développé un tel outil.

Exercice : mettre en œuvre sa stratégie de recherche

Mettons à présent ces notions en pratique. Trouvez dans l’archive Software Heritage :

1. Le code du programme LanguageTools.
2. Le code contenant les mots « you are not expected to understand this ».
3. Le code correspondant aux dépôts https://github.com/CatalaLang/catala et rsync://ftp.gnu.org/gnu/gcc/gcc-4.9.3.
4. Le fichier composé des lignes suivantes :

    #include <stdio.h>
   
    int main(void) {
        printf("Hello, World!\n");
    }
   

5. Le répertoire dont le SWHID est swh:1:dir:f72ab78156c5a4f05d394afa7a2f5911e1f33e27.

Choisir l’identifiant pérenne à intégrer dans une citation

Maintenant que vous savez naviguer dans l’archive et que vous avez vu ci-dessus les différents types de SWHIDs permettant de répondre aux différents besoins de citation d’un logiciel, donnons ci-dessous deux cas concrets. Dans ces situations, des identifiants pérennes bien choisis sont nécessaires pour répondre aux besoins des chercheurs qui souhaitent faire référence à des logiciels ou des portions de code source dans leurs productions académiques.

1. Une doctorante souhaite citer les logiciels utilisés pendant sa thèse pour permettre à ses lecteurs d’identifier et retrouver le code source correspondant, et de reproduire les résultats présentés dans son manuscrit. Elle a notamment utilisé le package R {rdss} pour une partie de ses analyses statistiques. Comme de nombreux autres packages R, {rdss} est seulement disponible sur la forge GitLab.com. Bien que librement téléchargeable, ce package pourrait ne plus être disponible du jour au lendemain, si la forge GitLab.com fermait soudainement ses portes, ou si son auteur en retirait ce package sans préavis. Les résultats présentés dans la thèse de cette doctorante seraient alors impossibles à auditer et à reproduire par les membres de son jury, ou par les futurs lecteurs de son travail. Comment peut-elle fournir un identifiant pérenne pour permettre à ses lecteurs d’accéder durablement à la version de {rdss} utilisée dans son manuscrit, à savoir la version (ou release) 1.1.1 ?

2. Un chercheur rédige un article cherchant à comparer la performance de divers algorithmes de fouille de textes, ou text mining, une méthode utile notamment aux historiens. Un lot de méthodes efficaces en fouille de textes est par exemple implémenté dans le package R {tm}. Notre chercheur pense avoir développé des fonctions en langage R encore plus rapides et économes en temps de calcul sur de grands jeux de données, en apportant des améliorations décisives à certains endroits du package {tm}. Par exemple, en considérant la version 0.7-9 du package {tm}, il souhaite signaler qu’il a mis au point une version plus rapide d’une fonction nomméetm_scan_one, dont le code est situé dans le fichier src/scan.c du package. En particulier, ce chercheur a apporté une amélioration décisive à la portion de code comprise entre les lignes 46 à 65, écrite en langage C. Comment peut-il faire référence de manière pérenne à cette portion de code dans son projet de publication ?

Solutions

1. Le but est ici de citer une version d’un logiciel : le bon identifiant SWHID est donc un identifiant portant sur la release. Sur la page adéquate de l’archive Software Heritage, on peut sélectionner la “release” 1.1.1, puis obtenir l’identifiant de version swh:1:rel:ef8ba743282a602d8b105ce82e1f6f48779d7998 grâce au menu Permalinks situé à droite de l’écran (Fig. 2).

2. Le but est ici de citer un extrait de code contenu dans un fichier source, à une étape donnée du développement d’un logiciel. Le bon identifiant SWHID est donc un identifiant de type content, c’est-à-dire, portant sur le contenu d’un fichier précis. Sur la page adéquate de l’archive Software Heritage, on peut sélectionner la “release” 0.7-9 du package, puis les lignes 46 à 65, pour enfin obtenir l’identifiant de contenu swh:1:cnt:e76e4f8b6a1d34dcb55cebaa0f4b91e5a186dd08 grâce au menu Permalinks situé à droite de l’écran (Fig. 3).

Archiver du code source

Dans cette section, vous allez principalement vous placer du point de vue des producteurs de code source, en créant un dépôt contenant un bref extrait de code et en assurant son archivage sur Software Heritage. Toutefois, rappelons qu’il n’est pas nécessaire d’être l’auteur d’un logiciel pour en demander l’archivage sur Software Heritage.

Dans quels cas archiver manuellement du code source

La grande majorité du code source archivé sur Software Heritage provient des « moissons » automatiques effectuées périodiquement depuis différentes sources. Notons que ces moissons automatiques sont faites « sans filtre » : Software Heritage n’effectue pas de test technique pour vérifier si un logiciel fonctionne.

Entre ces moissons périodiques, tout auteur ou utilisateur de logiciel a la possibilité de déclencher manuellement l’archivage d’un nouveau dépôt, ou la mise à jour d’un dépôt existant. Il s’agit de l’option « Save Code Now », permettant de soumettre l’URL d’un dépôt de code source qui sera alors inspecté puis archivé par Software Heritage dans son état le plus récent. Il existe au moins deux cas où vous pourrez souhaiter utiliser cette option :

1. Vous êtes utilisateur d’un logiciel et avez utilisé sa toute dernière version pour produire les résultats d’un article que vous vous préparez à soumettre. Vous souhaitez utiliser un SWHID judicieusement choisi (en l’occurrence, un SWHID de type release) pour citer ce logiciel dans votre article. Malheureusement, la dernière version de ce logiciel n’a pas encore été moissonnée automatiquement par Software Heritage, et le SWHID correspondant ne peut donc pas être encore être produit. Vous souhaitez donc utiliser l’option « Save Code Now » afin que Software Heritage visite à nouveau le dépôt de ce logiciel, et en archive la dernière version. Le SWHID dont vous avez besoin sera alors disponible.
2. Vous êtes auteur d’un logiciel développé sur la forge GitLab.com et vous souhaitez le publier rapidement. Vous ne pouvez pas attendre que le dépôt GitLab soit moissonné automatiquement et souhaitez en déclencher l’archivage tout de suite afin de pouvoir fournir une URL stable (et un SWHID) dans l’article de présentation de votre logiciel.

Étudions concrètement le premier de ces deux cas, avec le point de vue d’un utilisateur non-développeur.

Vérifier que la version archivée d’un dépôt est à jour

À un instant donné, il se peut que la version d’un logiciel actuellement disponible sur l’archive Software Heritage corresponde à une version antérieure à celle disponible sur la source officielle. Cela est particulièrement susceptible de se produire pour les logiciels en développement très actif dont l’évolution est rapide, avec parfois plusieurs dizaines de nouvelles révisions par jour. En effet, Software Heritage est une archive et non une forge, et n’a donc pas vocation à offrir en temps réel les dernières versions de l’ensemble des logiciels référencés. On peut néanmoins vérifier aisément si la version disponible sur l’archive Software Heritage est à jour.

Prenons l’exemple d’un logiciel libre développé collaborativement sur la forge logicielle GitHub : le package citar pour l’éditeur de texte Emacs. En naviguant sur le dépôt correspondant de l’archive Software Heritage (Fig. 4), on peut repérer la date du dernier snapshot effectué sur le dépôt GitHub (ici encadrée en bleu), ainsi que le hash (c’est-à-dire l’identifiant) de la dernière modification connue sur ce dépôt (ici encadré en vert). En comparant ces éléments avec la date et le hash de la dernière modification effectuée sur le dépôt GitHub d’origine, on peut donc savoir si la version archivée est à jour ou non.

Notons qu’une extension de navigateur, UpdateSWH, disponible pour les principaux navigateurs web, facilite cette opération. Après l’avoir installée, il suffit de visiter le dépôt d’origine d’un logiciel sur une forge moissonnée par Software Heritage. Une icône s’affiche alors à droite de l’écran, accompagnée d’une infobulle précisant si la version de la forge de développement coïncide ou non avec celle de Software Heritage (Fig. 5). Ici, la dernière version de citar disponible sur GitHub est plus récente que celle archivée sur Software Heritage : les modifications les plus récentes n’ont donc pas encore été archivées.

En pratique : archiver du code source que vous avez écrit

Afin de reprendre le cas d’usage le plus fréquent, vous allez créer un dépôt sur une forge logicielle basée sur Git, avant d’y éditer des extraits de code. Git est un logiciel de versionnement avancé, permettant de gérer finement les versions successives de fichiers (au format texte brut principalement) d’un même projet lors de l’avancée du travail, de garder la trace de chaque modification effectuée (date, auteur, contenu) et de pouvoir revenir à des versions antérieures de ces fichiers. Il existe d’autres systèmes de gestion de version (par exemple Mercurial ou SVN), mais la plupart des forges logicielles actuelles utilisent Git, et offrent ainsi une plateforme web centralisant l’avancée d’un projet, en particulier dans le cas d’un développement collaboratif.

Créer un dépôt GitLab

1. Si ce n’est pas déjà fait, commencez par vous créer un compte sur GitLab.com.
2. Vous pourrez ensuite vous connecter sur cette forge avec vos identifiants.
3. Dans l’interface de GitLab, ou en suivant ce lien, choisissez l’option « Créer un projet vide », dans lequel vous hébergerez par la suite du code source.
4. Choisissez par exemple Test SWH comme nom de projet, et veillez à ce que le « Niveau de visibilité » du projet soit réglé sur « Public ». (Sans cela, le code source du projet ne serait accessible que par vous, et ne pourrait donc pas être moissonné par Software Heritage.)
5. Validez enfin la création de ce nouveau projet en cliquant sur le bouton « Créer le projet » (Fig. 6).

Écrire une portion de code

Vous devriez alors arriver sur la page du nouveau projet Test SWH ainsi créé. Ce projet est pour l’instant vide, à l’exception d’un fichier README.md prérempli.

Vous pouvez à présent insérer un extrait de code dans votre projet. Par exemple, vous pouvez réutiliser l’extrait de code suivant (en langage Bash), prenant en argument une année, et déterminant si cette année est bissextile ou non.

#!/usr/bin/env bash

# Check arguments:
if [[ $# -ne 1 || ! $1 =~ ^[0-9]*$ ]]
then
    echo "Usage: leap.sh <year>"
    exit 1
fi

# Do we have a leap year?
if (($1 % 400 == 0)) || ( (($1 % 4 == 0)) && (($1 % 100 != 0)) )
then
    echo "true"
else
    echo "false"
fi

exit 0

Pour ce faire, dans l’interface de GitLab.com, cliquez sur le bouton + situé en haut de la page du dépôt, puis choisissez « Nouveau fichier ». Dans la nouvelle fenêtre qui s’ouvre, collez l’extrait de code ci-dessus, puis attribuez le nom leap.sh à ce fichier source dans le champ Filename. Enfin, en bas de la page, cliquez sur Valider les modifications pour effectuer une révision (ou commit). Après cela, le fichier leap.sh est ajouté à votre dépôt, et une révision associée à la création de ce fichier a bien été enregistrée (Fig. 7).

Ajouter une licence

Maintenant que votre dépôt comporte du code, il est nécessaire de lui ajouter une licence pour en spécifier les conditions d’utilisation. Cela peut être réalisé très aisément dans l’interface de GitLab.com, en cliquant sur le lien « Ajouter une LICENCE » dans la page d’accueil du dépôt. Vous pouvez alors choisir la licence de votre choix dans la liste déroulante « Appliquer un modèle ». Choisissez par exemple la licence GNU Affero General Public License v3.0, puis cliquez à nouveau sur « Valider les modifications » en bas de la page. Cela crée une nouvelle révision associée à l’ajout du fichier LICENSE dans votre dépôt (Fig. 8).

Déclencher l’archivage du dépôt

Votre dépôt GitLab possède désormais un contenu raisonnable : un fichier de code en langage Bash, une licence en spécifiant les conditions d’utilisation, et un template de fichier README. Ce dépôt peut à présent être archivé sur Software Heritage. Deux options sont possibles pour cela :

1. Manuellement, avec l’option « Save Code Now ». Visitez la page dédiée sur le site de Software Heritage. Entrez l’URL de votre dépôt Test SWH créé sur GitLab.com. Notons que, par défaut, le champ « Origin type » est correctement attribué, avec la valeur git (qui correspond effectivement au cas d’un dépôt GitLab). Collez dans le champ « Origin URL » l’adresse que vous pouvez récupérer sur la page GitLab de votre dépôt, en cliquant sur le bouton « Code », puis « Cloner avec HTTPS » (Fig. 9).

2. Alternative : vous pouvez également choisir d’utiliser à la place le plug-in de navigateur déjà mentionné plus haut. Cliquez sur l’icône « disquette » affichée à droite de votre écran afin de déclencher l’archivage (Fig. 10).

Pour aller plus loin : décrire un logiciel avec CodeMeta

Fournir un fichier README suffisamment détaillé (voir par exemple le fichier README du package R {tapas}) constitue une étape importante pour expliquer les finalités d’un logiciel. Ajouter un fichier descriptif CodeMeta facilite l’identification d’un logiciel.

Ajouter des métadonnées pour rendre son logiciel identifiable

Les logiciels sont des ressources labiles : leur cycle de vie peut s’étendre sur plusieurs décennies, leurs fonctionnalités évoluent, leur nom n’est pas toujours fixe, leur plateforme d’origine peut aussi changer, y compris en cours du développement d’une même version.

De fait, ces ressources peuvent être difficiles à identifier. Dans le cas des logiciels, les métadonnées doivent entre autres permettre d’exprimer les auteurs, les changements de versions, la ou les licences, mais aussi les relations entre les différentes productions académiques. Les métadonnées aident à identifier le logiciel ainsi que son contexte de création et d’utilisation. Il existe deux grandes catégories de métadonnées.

1. Les métadonnées intrinsèques fournissent des informations essentielles pour assurer la préservation et l’utilisabilité à long terme des logiciels. Elles sont contenues dans un fichier texte à vocation descriptive, souvent intitulé README ou DESCRIPTION, situé à la racine du répertoire du code source du logiciel. C’est pourquoi, très souvent, les auteurs de logiciels sont les premiers et les principaux fournisseurs de métadonnées intrinsèques.

2. Les métadonnées extrinsèques peuvent fournir quant à elles des informations importantes sur le contexte et la provenance du logiciel : par exemple, sur quelle forge le logiciel a été développé. Ces informations aident les utilisateurs à localiser le logiciel, à identifier la communauté qui l’utilise. Ces métadonnées renseignent aussi sur la relation entre le logiciel et d’autres produits de recherche : des publications, des jeux de données. Ces métadonnées ne sont pas incluses dans les fichiers du code source, c’est pourquoi elles sont qualifiées d’extrinsèques. Elles peuvent être ajoutées par des opérateurs extérieurs : des services éditoriaux, des agrégateurs, des catalogues, etc. Elles peuvent être aussi fournies par la personne qui a écrit le code source, comme c’est le cas avec l’archive ouverte HAL. Les informations à compléter sont indiquées dans un formulaire de saisie.

La personne à l’origine du logiciel joue un rôle majeur dans le processus descriptif du logiciel. Des métadonnées riches contribuent à la réutilisation et l’identification des logiciels.

CodeMeta, la pierre de Rosette des auteurs de logiciels

Fournir des métadonnées intrinsèques incombe à l’auteur du logiciel. Or, décrire un logiciel est une pratique bien moins codifiée que décrire un ouvrage ou un article. Si certaines métadonnées semblent relever de l’évidence (nom du logiciel, auteurs, version, licence), il n’existe pas de standard indiquant un noyau minimal d’informations à fournir. La liste des métadonnées dépend de l’usage ciblé ainsi que le note S. Morrissey :

« How do we describe software effectively ? The list of properties to be described will vary according to the purposes for which we collect software¹⁰. »

De plus, il existe de nombreux vocabulaires descriptifs, ayant chacun leurs spécificités. Non seulement il faut déterminer les éléments à décrire, mais il faut également considérer dans quel vocabulaire les exprimer. Voici un exemple de correspondances entre métadonnées issues de différentes plateformes :

De même, cette fois à l’échelle du logiciel et non plus de la plateforme, comparez le fichier DESCRIPTION d’un package R et le fichier Project.toml d’un package Julia. Ces deux fichiers ont le même objectif (indiquer auteurs, versions, dépendances, etc.), mais vous pouvez constater que leur syntaxe diffère sensiblement en fonction du langage, ce qui rend difficile leur moisson et leur traitement automatiques.

CodeMeta résout ces problèmes en jouant le rôle de connecteur entre une vingtaine de vocabulaires : il est comparable à une table de concordance. CodeMeta présente aussi l’avantage d’être adapté aux besoins académiques. Il permet ainsi d’indiquer un financement, un lien avec une publication, un domaine disciplinaire. Les métadonnées sont lisibles par l’humain comme par les machines, ce qui augmente le potentiel de “découvrabilité” d’un logiciel décrit via un fichier CodeMeta, conçu avec le CodeMeta Generator.

En pratique : utilisation de CodeMeta Generator pour documenter votre dépôt

Ajoutez un fichier CodeMeta dans le dépôt de la leçon afin de renseigner quelques métadonnées utiles sous un format unifié. Ce fichier, qui sera nommé codemeta.json, est donc au format JavaScript Object Notation, l’un des formats populaires de stockage de (méta)données. Cette syntaxe est néanmoins très fastidieuse à saisir manuellement, et on utilise donc plutôt habituellement des interfaces de saisie pour générer de tels fichiers.

En effet, consultez par exemple ce fichier CodeMeta, fournissant les métadonnées pour le serious game Plagiator. Bien que l’on puisse comprendre la structure globale d’un tel fichier, et deviner le sens de la plupart des champs (contributor, email, dateCreated, etc.), il semble clair que la saisie manuelle de ce genre de fichier serait inconfortable pour l’auteur d’un logiciel.

Vous pourrez donc préférer utiliser des interfaces graphiques intuitives telles que CodeMeta Generator (il en existe d’autres ?) pour produire des fichiers CodeMeta.

Exercice. Créons un fichier CodeMeta correspondant à votre dépôt.

1. Sur le site de CodeMeta Generator, remplissez au moins les champs les plus essentiels (par exemple : Name, Authors, License(s), Programming Language, Code repository) avec les informations adéquates.
2. Cliquez sur le bouton « Generate codemeta.json v3.0 » en bas de la page afin d’obtenir le contenu d’un fichier codemeta.json.

Exercice. Pour terminer, placez ce fichier codemeta.json à la racine de votre dépôt.

1. Copiez le contenu proposé par CodeMeta Generator à l’issue de l’étape précédente.
2. Dans votre dépôt sur GitLab.com, créez un nouveau fichier nommé codemeta.json, et collez-y ce contenu.
3. Cliquez sur « Valider les modifications » afin de créer une nouvelle révision (commit) associée à la création de ce fichier.

Conclusion

Une recherche plus transparente et plus traçable nécessite non seulement un accès pérenne aux jeux de données, mais également aux logiciels utilisés dans les travaux académiques. Par leur structure, leurs modalités de conception et de diffusion, les logiciels doivent être archivés avec des solutions spécifiques telles que la bibliothèque de code source Software Heritage. Si les forges constituent de puissants outils de développement, elles ne préservent pas les contenus sur le temps long. Grâce aux différentes types d’identifiants pérennes, il est possible de garantir l’accès aux logiciels et à leurs composants de manière fiable. Enfin, que le logiciel soit composé de millions de lignes de code ou qu’il soit un court script, il représente une production académique méritant d’être archivée et citée. Les pratiques académiques inhérentes au logiciel sont encore en plein développement. Intégrer un socle de bonnes pratiques dès à présent vous bénéficiera sur la durée.

Avez-vous plus de questions ?

Les auteur(e)s se feront un plaisir de répondre à toute question que vous pouvez avoir.

• Pour toute demande relative à Software Heritage, consulter la Foire Aux Questions ou utiliser le formulaire de contact.
• Pour suivre l’actualité de Software Heritage, consulter le blog dédié ou abonnez-vous à la newsletter.

Remerciements

Les auteurs souhaitent remercier Joenio Marques da Costa, backend developer de la plateforme CorTexT.

Notes de fin