Citable Lessons

<font size=5 color=blueyellow>**Citable lessons**</font> **Contributions**: <a><img src="https://img.shields.io/badge/CodeRefinery-purple?style=plastic"/></a> **Keywords**: <a><img src="https://img.shields.io/badge/Citable lesson-996300?style=plastic"/></a> <a><img src="https://img.shields.io/badge/Zenodo-green?style=plastic"/></a> <a><img src="https://img.shields.io/badge/Workflow-3232ff?style=plastic"/></a> <a><img src="https://img.shields.io/badge/XXX-aqua?style=plastic"/></a> <a><img src="https://img.shields.io/badge/YYY-red?style=plastic"/></a> <a><img src="https://img.shields.io/badge/ZZZ-gold?style=plastic"/></a> **Contents of this document and quicklinks**： [TOC] --- ## 1. Overview Citable lessons is for people who have created code and scripts for research activities and lesson materials for workshops and webinars, and want to share these materials on internet. But simply putting these materails somewhere online does not mean it is feasible by others to reach and to cite properly. Therefore it is especially important to publish these materials in professional communities, and accordingly, the developers of code and lesson materials can get proper credits and make these materials impactful within the communities. In Autumn 2021, CodeRefinery has started working on this topic to make the developed code, scripts, and lesson materials citable. [Meeting notes](https://hackmd.io/pr3hps9SRgWwSPOHWRMWXA) and [blogpost summaries](https://coderefinery.org/blog/2021/11/21/towards-citable-lessons/) are published online and concluded below: - give contributors/developers better credits so that they can display relevant metrics about their contributions - assign a digital object identifier (DOI) to all lessons so that these materials become persistent and findable - [Zenodo](https://zenodo.org/) will be used as it is a well-established service and it integrates well with Github repositories --- ## 2. Technical procedures - what metadata should be included? - `CITATION.cff` containing author information - full names, affiliations - orcid? - other information? - try `.zenodo.json` if `CITATION.cff` is missing or is not enough to provide right categories to generate a new `CITATION.cff` file - should we distinguish authors and contributors? - one case from the Carpentries (unix shell lesson) - http://doi.org/10.5281/zenodo.3266823 - how can we handle this issue? - all contributors are equal? - have some classifications? - creator - contributor/editor (reviewing/approving contributions) - contributor/other (minor contributions) - the number of commits for each contributor? - if yes, can we include these info in the `CITATION.cff` file? - other info for authors? - archiving each lesson to a PDF document :::info #### For CodeRefinery: - CFF can distinguish (it seems) between author and editor - we offer authorship to everybody who contributed a non-trivial contribution but it remains opt-in - lessons can have one or more editors - editors: also opt-in - it will be editor's job to make sure that significant contributors are added to CITATION.cff - acknowledgements are on the lesson page - in tricky cases, call in a meeting - we reach out to possible authors via github issues with mentions (unless their contribution was outside of git) - when reaching out, we ask with what contact they want to be mentioned (orcid, full name, institution?) ::: :::success #### CodeRefinery website or manuals text We hope to acknowledge all contributors to our material. We acknowledge in these ways: * **Editors** take an overall, long-term view, set the overall strategy, and manage the fit of the various sections. They merge pull requests (but so can others). * **Contributors/Authors** have made contributions which are considered significant by someone, and take responsibility to some limited parts they have contributed to. * **Acknowledgees** have made other contributions. Editors and contributors are listed in the `CITATION.cff` file within each repository and are includes as authors in the archived DOI in Zenodo. Acknowledgees are listed on the Github contributors page and/or READMEs. If you have been linked here, you might have been asked if you want to be listed as an author. If someone has asked you, then don't worry if you contribution is enough: the threshold is not high. If so, consider: - Your name and info will be included in the Zenodo citation, which is permanent - You will be included in future releases as well, unless you ask to be removed - Please send us your preferred citation name [and anything else] Editors should be proactive reach out to people when they contribute, but also you should send a pull request to be included in CITATION.cff if you desire. Note that nothing of the above is defined as "git or in-writing contributions". Anyone is welcome to take a long-term view of the lesson to become a future editor. ::: --- ## 3. Workflow to convert lesson materials to PDF documents - sphinx lesson materials to PDF documents - straightforward to conversion Sphinx lessons to PDF documents - PDF documents will be generated automatically as part of a "release" workflow - [suggested workflow to make lessons citable via Zenodo](https://coderefinery.org/blog/2021/11/21/towards-citable-lessons/) - [Automation procedures for multiple lessons](https://hackmd.io/@enccs/B1skeYDHp) - collect info for all github repos - each lesson has its own `CITATION.cff` document - extracting the number of commits for each contributor(useful?) - **Todo**: update settings in sphinx.yml so as to achieve automation - publish PDF documents on Zenodo - how to handle the published Zenodo document after updating lesson materials if the lesson materials will be continuously updated for workshops/webinars? - just publish the 1st version of the lesson materials? - publish another version if we have significant improvement on the lesson materials? --- ## 4. ENCCS-related lessons - [mermaid graph chart](https://hackmd.io/@yonglei/mermaid-enccs-lesson) for lessons (**parts of CodeRefinery lessons are included**) - [markmap graph chart](https://hackmd.io/@yonglei/markmap-enccs-lesson) for lessons - [GPU programming BPG](https://github.com/ENCCS/gpu-programming-bpg) - latex format --- ## 5. Summary - author information - classifications of contributors - updating sphinx.yml to achieve automatioin - sphinx.yml is (manually) synced across all repos - Needs a new release.yml (ideally that uses the pdf from sphinx.yml, but how to make them depend on each other?) that does the zenodo upload - republish the same lesson ==social media summary==: > We talked about citable lessons. The goal is to better acknowledge people who have contributed. We roughly agreed on citation levels "editors", "authors", and "acknowledgees" (see https://coderefinery.github.io/manuals/lesson-credits/). We already build PDFs of all lessons so we'll set up releases to upload to Zenodo. #CodeRefinery ---