search

programminghistorian / ph-submissions

The repository and website hosting the peer review process for new Programming Historian lessons
http://programminghistorian.github.io/ph-submissions
135 stars 112 forks source link

Préserver et rendre identifiables les logiciels de recherche avec Software Heritage #616

Open marie-flesch opened 2 months ago

marie-flesch commented 2 months ago

Programming Historian en français a reçu une proposition de leçon originale intitulée "Préserver et rendre identifiables les logiciels de recherche avec Software Heritage", de la part de Sabrina Granger, Baptiste Mélès et Frederic Santos.

Cette leçon a trois objectifs pédagogiques principaux :

  1. Comprendre les enjeux de l'archivage du code source des logiciels de recherche, et ses spécificités par rapport aux jeux de données.
  2. Archiver des logiciels, qu'ils soient écrits par vous-même ou par un.e collègue.
  3. Comprendre les différents besoins d'identification inhérents au logiciel. Obtenir et utiliser des identidiants intrinsèques pour une meilleure reproductibilité de ses travaux.

La proposition a été évaluée et acceptée par l'équipe de Programming Historian en français. Elle répond à nos critères en termes de science ouverte et de pérennité.

La leçon sera envoyée par ses auteurices fin mai 2024. À sa réception, son suivi éditorial sera confié à un·e des membres de l'équipe de Programming Historian en français.

Si nous n'avons pas reçu la leçon à la date convenue, nous contacterons ses auteurices. En cas de non-réponse, nous fermerons ce ticket.

Programming Historian en français a pour but d'offrir un environnement académique ouvert, qui permet aux membres de la communauté de se sentir libres d'examiner des idées en détail, de poser des questions, de faire des suggestions, ou de formuler des demandes de clarification. Nous insistons sur l'importance de faire en sorte que cet espace de discussion reste respectueux et exempt de tout harcèlement pour tous les contributeur(trice)s, quels que soient leur genre, leur identité et leur expression de genre, leur orientation sexuelle, leur handicap, leur apparence physique, leur masse corporelle, leurs origines, leur âge, leur religion, ou leur expérience technique. Nous ne tolérons pas, sous quelque forme que ce soit, le harcèlement ou les attaques ad hominem contre les membres de la communauté. Les participant·es qui violeraient ces règles pourront être exclu·es de la communauté à la discrétion du comité éditorial. Si quelqu'un est témoin ou pense avoir été victime des agissements décrits plus haut, veuillez prendre contact avec notre médiatrice Hélène Huet. Merci de nous aider à créer un espace de discussion et d'échange sûr. Contacter notre médiatrice n'a aucun impact sur l'issue du processus d'évaluation par les pairs.

marie-flesch commented 1 month ago

Nous avons reçu la leçon, et @DMathelier s'est proposée pour en assurer le suivi ✨

marie-flesch commented 1 month ago

Les auteurices de la leçon sont @sabrinagranger, @BapMel et @frederic-santos.

charlottejmc commented 1 month ago

Bonjour @DMathelier, @sabrinagranger, @BapMel et @frederic-santos,

Vous trouverez les fichiers ici :

Vous pouvez parcourir l’aperçu de la soumission ici :

This descriptive element enables screen readers to read the information conveyed in the images for people with visual impairments, different learning abilities, or who cannot otherwise view them, for example due to a slow internet connection. It's important to say that alt-text should go further than repeating the figure captions.

We have found Amy Cesal's guide to Writing Alt Text for Data Visualization useful. This guide advises that alt-text for graphs and data visualisations should consist of the following:

alt="[Chart type] of [data type] where [reason for including chart]"

What Amy Cesal's guide achieves is prompting an author to reflect on their reasons for including the graph or visualisation. What idea does this support? What can a reader learn or understand from this visual?

The Graphs section of Diagram Center's guidance is also useful. Some key points (relevant to all graph types) we can take away from it are:

For general images, Harvard's guidance notes some useful ideas. A key point is to keep descriptions simple, and adapt them to the context and purpose for which the image is being included.

Would you feel comfortable making a first draft of the alt-text for each of the figures? This is certainly a bit time-consuming, but we believe it is very worthwhile in terms of making your lesson accessible to the broadest possible audience.

Merci !

anisa-hawes commented 1 month ago

Bonjour Sabrina @sabrinagranger, Baptiste @BapMel, and Frédéric @frederic-santos,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 2: Initial Edit.

In this phase, your editor Daphné @DMathelier will read your lesson, and provide some initial feedback. Daphné will post feedback and suggestions as a comment in this issue, so that you can revise your draft in the following phase (Phase 3: Revision 1).

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#3d7c81', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 1 <br> Submission
Who worked on this? : Publishing Assistant (@charlottejmc) 
All  Phase 1 tasks completed? : Yes
Section Phase 2 <br> Initial Edit
Who's working on this? : Editor (@DMathelier)  
Expected completion date? : July 14
Section Phase 3 <br> Revision 1
Who's responsible? : Authors (@sabrinagranger, @BapMel, @frederic-santos) 
Expected timeframe? : ~30 days after feedback is received

In the meantime, I've sent you each an invitation to join us as Outside Collaborators here on GitHub. This will give you the 'write access' you'll need to edit your alt-text as Charlotte suggests above. Your lesson file is here: /fr/en-cours/originales/preserver-logiciels-recherche.md, and you can edit it directly.

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

frederic-santos commented 4 weeks ago

Bonjour à toute l'équipe PH : @DMathelier, @anisa-hawes, @marie-flesch et @charlottejmc !

Je viens de pousser un nouveau commit qui devrait résoudre (j'espère !) vos commentaires et suggestions ci-dessus. Merci pour votre première relecture !

Of course, mes co-auteurs @sabrinagranger et @BapMel peuvent également m'engueuler si ce n'est pas le cas ;)

À bientôt et merci !

DMathelier commented 4 weeks ago

Bonjour Sabrina @sabrinagranger, Baptiste @BapMel, and Frédéric @frederic-santos,

J’ai fini de relire votre leçon, un grand merci pour votre travail très utile !

Avant que nous passions à la phase d’évaluation j’ai des remarques et améliorations à vous proposer. Désolée d’avance pour le pavé mais il s’agit des corrections habituelles et vous êtes libres de ne pas toutes les accepter évidemment :)

Interrogations

Propositions de correction

Le plus simple est de chercher son dépôt officiel dans un moteur de recherche ou un catalogue de logiciels (ex. catalogue des logiciels du MédiaLab de SciencesPo).

Par exemple, 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).



- [X] §56 : ajouter une virgule après le 2e tiret d’incise : `fichiers —, obtenir`

- [X] §63 : hyperliens seulement sur `package R {tm}` et sur `fichier src/scan.c`

- [X] §66 : `pourpermettre` → `pour permettre`

- [X] §75 : préciser le nom de l’extension ?
    - `Notons qu’une extension de navigateur, [UpdateSWH](https://www.softwareheritage.org/browser-extensions/), disponible`

- [X] §76 : la fig. 5 n’apparaît pas. Un problème de lien peut-être ?

- [X] §90 : supprimer le lien actuel sur README et ajouter une note plutôt (ou une précision entre parenthèses)
    - Ajouter ce lien sur README : https://www.makeareadme.com
    - Ajouter une note ou entre parenthèses : `(voir par exemple le fichier README du`[package tapas](https://archive.softwareheritage.org/swh:1:cnt:0918fd32b5eddc85aaaeb35da83a749795e703bc;origin=https://github.com/wfinsinger/tapas;visit=swh:1:snp:fb13c70f7d5edc7515756d6f1c01a3f3b1a69e72;anchor=swh:1:rev:5f3d58423904da1b0bf368886ccf31d97956f7b3;path=/README.Rmd)

- [X] §93 : `Les métadonnées intrinsèques : elles fournissent` → `Les métadonnées intrinsèques fournissent`
- [X] §94 : remplacer le point d’interrogation par un point.
- [X] §94 : supprimer l’hyperlien sur `catalogues` qui renvoie à un exemple précis. Pour évoquer cet exemple, préférer une précision entre parathèse ou une note.

- [X] §104 : supprimer les `:` après `Exercice`
- [ ] §107 : supprimer le 2e `Exercice` et commencer le nouveau paragraphe par `Pour terminer`

- [ ] §109 : proposer une conclusion plutôt qu’un résumé ?
[name=sabrina] @frederic-santos @BapMel : svp, avant le 22/07, pourriez-vous jeter un oeil à cette proposition, volontairement pas insérée dans le texte? https://hedgedoc.softwareheritage.org/conclusion-PH#

- [X] §111 : fusionner les deux premières puces
    - `Pour toute demande relative à Software Heritage, consulter la foire aux questions ou utiliser le formulaire de contact.`
- [X] §111 : reformuler la dernière puce
    - `Pour suivre l’actualité de Software Heritage, consulter le blog dédié ou inscrivez-vous à sa newsletter`

**Hyperliens**
- En règle générale : privilégier les notes pour les précisions et les exemples, et les hyperliens pour les liens directs à un objet **cité** (exemple, ressource, outil...)
    - Ex. §90
- Réduire la taille des hyperliens (sur 2/3 mots max)
    - Ex. § 22 : hyperlien sur `documentation` uniquement
    - Ex. § 44 : hyperlien sur `documentation technique` uniquement (ou sur `types de SWIDS disponibles` éventuellement)
    - Ex. §94 : hyperlien sur `formulaire de saisie` uniquement
- Le lien du paragraphe 2 ne semble pas fonctionner.

**En règle générale, corrections typographiques**
- Supprimer les virgules superflues devant les conjonctions de coordinations (surtout : mais, ou, et)
    - `, et` → `et` | `, ou` → `ou`
    - Ex. §22 `sans créer de compte et il n’est pas nécessaire
- ~Mettre des apostrophes françaises partout : `’` → `’`~
- ~Mettre des guillemets français : `«` et `»`~
- Dans les listes
    - Mettre des majuscules à chaque ligne
    - Mettre des points ou des points-virgules à la fin de chaque ligne (surtout s’il s’agit de phrases complètes)
    - Ex. § 31, §32
- Unifier : `par exemple` ou `ex.` (mais pas les deux)
- Pour les légendes des figures, remplacer les `:` par un point
    - `Figure 1 : Tous` → `Figure 1. Tous`

Suite à cette première relecture, vous avez environ un mois pour intégrer les corrections proposées, donc disons idéalement jusqu’au **lundi 22 juillet** ? 
Pendant ce temps je vais rechercher les deux expert(e)s qui évalueront votre leçon lorsque celle-ci aura été modifiée.

Bon courage et n’hésitez pas demander des précisions sur ce ticket si besoin !
marie-flesch commented 3 weeks ago

Merci @DMathelier pour cette première relecture ! @frederic-santos, @BapMel et @sabrinagranger , en fait pas besoin de vous occuper des apostrophes et des guillemets, on va le faire nous-mêmes :) Pour les autres propositions, nous vous laissons appliquer celles qui vous semblent pertinentes.

frederic-santos commented 3 weeks ago

Bonjour Marie @marie-flesch et Daphné @DMathelier,

Nom d'un pingouin, quelle efficacité ! Merci beaucoup pour cette relecture attentive et ces corrections ! Je viens de pousser quelques commits qui en implémentent déjà une bonne partie ; nous allons discuter avec mes co-auteurs pour corriger le reste dans la quinzaine à venir.

J'ai juste deux remarques/questions techniques de mon côté :

Le lien du paragraphe 2 ne semble pas fonctionner.

Théoriquement, il fonctionnera sur le site "réel" de PH (je pense ?). C'est un lien relatif vers une autre leçon hébergée sur PH, et je crois justement que les instructions aux auteurs recommandaient de donner un lien relatif plutôt qu'un lien absolu si vous voulait faire référence à une autre leçon. Est-ce toujours le cas ?

§76 : la fig. 5 n’apparaît pas. Un problème de lien peut-être ?

Oui, c'est lié à la remarque faite par Charlotte plus haut. Nous avons fait une boulette dans la version initiale de l'article, en insérant pour la Figure 5 un lien vers un fichier citar_GitHub.png, alors que le PNG que nous avons transmis s'appelait en réalité citar_GitHub_raw.png. J'ai tenté de corriger ça de mon côté, mais visiblement, pas de la bonne manière. 😀

Merci en tout cas, nous vous préviendrons quand tout sera corrigé !

charlottejmc commented 3 weeks ago

Bonjour @frederic-santos et @DMathelier,

En effet, j'attendais juste une confirmation avant d'insérer le bon lien vers la Figure 5. C'est donc bon maintenant, merci !

Je me chargerai en Phase 6 des corrections typographiques (guillemets, apostrophes, etc.). Ceci fait partie du travail que faisons @anisa-hawes et moi pendant la phase de "typesetting", et qui assure l'uniformité visuelle de nos leçons à travers les quatre langues. Ne vous inquiétez donc pas trop pour la forme !

Un certain nombre de points relevés par @DMathelier sont en fait dûs à des changements que j'ai faits moi-même en créant le fichier ! Par exemple, la forme des listes – dans nos consignes, nous demandons à ce qu'on n'utilise pas de ponctuation (points virgules, point final) à la fin de chaque ligne. Je les ai donc retirés du texte original soumis par les auteurs.

Merci ✨

anisa-hawes commented 3 weeks ago

Bonjour Sabrina @sabrinagranger, Baptiste @BapMel, and Frédéric @frederic-santos,

What's happening now?

Your lesson has been moved to the next phase of our workflow which is Phase 3: Revision 1.

This phase is an opportunity for you to revise your draft in response to @DMathelier's initial feedback. As @marie-flesch explains, @charlottejmc and I take care of all typographical adjustments as part of Phase 6 Sustainability + Accessibility. This ensures that all lessons are presented consistently across our four journals. Thank you for your understanding ☺️

I've checked to ensure that you have the 'write access' you'll need to edit your draft directly. (Baptiste @BapMel, I have sent you an invitation to join us as an Outside Collaborator, but I note that it is still pending. Please let me know if you have any difficulties gaining access.)

We ask authors to work on their own files with direct commits: we prefer you don't fork our repo, or use the Pull Request system to edit in ph-submissions. You can make direct commits to your file here: /fr/en-cours/originales/preserver-logiciels-recherche.md. @charlottejmc and I can help if you encounter any practical problems!

When you and Daphné are all happy with the revised draft, we will move forward to Phase 4: Open Peer Review.

%%{init: { 'logLevel': 'debug', 'theme': 'dark', 'themeVariables': {
              'cScale0': '#444444', 'cScaleLabel0': '#ffffff',
              'cScale1': '#3d7c81', 'cScaleLabel1': '#ffffff',
              'cScale2': '#444444', 'cScaleLabel2': '#ffffff'
       } } }%%
timeline
Section Phase 2 <br> Initial Edit
Who worked on this? : Editor (@DMathelier) 
All  Phase 2 tasks completed? : Yes
Section Phase 3 <br> Revision 1
Who's working on this? : Authors (@sabrinagranger, @BapMel, @frederic-santos)  
Expected completion date? : July 22
Section Phase 4 <br> Open Peer Review
Who's responsible? : Reviewers (TBC) 
Expected timeframe? : ~60 days after request is accepted

Note: The Mermaid diagram above may not render on GitHub mobile. Please check in via desktop when you have a moment.

sabrinagranger commented 6 days ago

@frederic-santos : mille mercis pour les modifications apportées! j'ai refait un tour (notamment pour modifier le tableau (§45 : agencement du tableau à revoir) comme demandé mais j'ai reçu des messages d'erreur. Stp, pourrais-tu vérifier si tout est ok?

anisa-hawes commented 6 days ago

Bonjour Sabrina @sabrinagranger,

I hope you're well. Thank you for your work on these revisions!

In your note above, you mention receiving error messages. Do you mean an error when you are making a commit to the ph-submissions repository?

I just wanted to clarify that when we make several commits in quick succession, our previous build-checks are automatically cancelled (then show with a red cross). But this doesn't mean that there has been a problem with your commit, and indeed we can be confident that everything is well in this case because your subsequent and most recent commits have been successful.

@charlottejmc and I are here to help with any practical questions about working with Markdown or the particulars of our repository. Please let us know if we can lend a hand! ☺️

sabrinagranger commented 6 days ago

Hello @anisa-hawes! Thanks for your super fast support. :) Here is what I got: image

sabrinagranger commented 6 days ago

I received these notifications after my commits

anisa-hawes commented 6 days ago

No problem @sabrinagranger. Yes, exactly. These notifications are only to let you know that the build checks have been skipped or cancelled because you made another commit before they had completed. Nothing to worry about here - the build checks have automatically cancelled because they have been interrupted.

Reviewing the commit log, we can review any build issues. You can be assured that everything is fine because your most recent commits have completed in full and been successful:

Screenshot 2024-07-10 at 14 07 39