# Open house on citable lessons

:::info
- Date and time: Aug 19, 12-15 CEST
- Zoom room: https://uit.zoom.us/j/61470327776
- This document: https://hackmd.io/@coderefinery/citable-lessons
:::

**Goal:** The overall goal for this event is to conclude on how we can make our lessons citable. To this end we need to
- Converge on a convenient workflow
- Decide which metadata to use. Three options are
-- maintain a .zenodo.json in the lesson repository
-- maintain a CITATION.cff in the lesson repository
-- use the https://allcontributors.org/ bot on GitHub.
The suggestion is that we use only one of these.
- We need to set priorities for which lessons we should work through and release at first. A suggestion is to go for the lessons that are part of the big workshops.
- For 1-2 example lessons: create a release and get a DOI on https://zenodo.org/ and a recommended citation https://help.zenodo.org/

**Distinguishing authors and contributors:**
- Contributor: everybody who contributed, any size contribution
- Author: we ask contributors whether they would prefer to be author or contributor
- Decide on per-lesson basis (may require contacting people)
- Contributors are not only people who have contributed with git commits, but could also be people that contributed with input and ideas in other form
- See also https://allcontributors.org/
- What to do with stuff that has been removed? Will it also remove contribution/authorship?
- In general, authorship is kept unless the author prefers to be removed?
- Example for is how Carpentries do it (unix shell lesson):
- https://github.com/swcarpentry/shell-novice/blob/gh-pages/CITATION
- http://doi.org/10.5281/zenodo.3266823
- See also categories that Zenodo understands: https://developers.zenodo.org/#representation (search for "creators" and "contributors")

Conclusions:
- we reach out to everybody and ask whether they want to be contributor or author
- if a person cannot be reached, we do not add the person without constent and rather add the person later once we reach them
- on Zenodo we start with "creator" (author) and "contributor" (other)
- Write definitions of the roles and post them on the CR webpage
- "creator": significant contributions
- "contributor"/Editor: reviewing/approving contributions
- "contributor"/Other: smaller contributions
- but we are a bit unsure whether one person can assume more than one role on Zenodo. probably yes. If so, maybe one occurence for the highest contribution is best.

**Follow-up as preparation for this meeting:**
- [ ] Try out the .zenodo.json
-- If a .zenodo.json is present in a repo, it has on Zenodo presedence over a CITATION.cff.
- [x] Try out the CITATION.cff file format
-- Support for this format on Zenodo only as of 28 July. Seemingly immature integration.
-- On https://sandbox.zenodo.org/ the CITATION.cff in the GitHub repo was ignored. Strange.
- [x] Try out the https://allcontributors.org/ GitHub bot.
-- Need each tentative contributor have a GitHub account? If so, this is a (severe) limitation. It is then better to add people manually in a CITATION.cff or in a zenodo.json.
- [ ] Try out how Zenodo extracts meta-data on authors with/without ORCID
- [x] As examples, make releases and DOI:s for a few lessons before the open house.
-- https://github.com/johanhellsvik/social-coding
- [ ] Try out how to autogenerate pdf:s from Sphinx via LaTeX
- [ ] ~~Research on how to autogenerate pdf:s from Jekyll~~

Conclusions:
- we start with .zenodo.json and later maybe add or migrate to CITATION.cff. We will not start with allcontributors (since it requires GitHub usernames, which are not persistent). Outside-GitHub contributors can be added to the metadata via issues/PRs.
- update: CITATION.cff actually seems to have worked and might be better than .zenodo.json, better because GitHub understands it and presents a "cite as" button

**Questions to clarify:**
- We should archive both source and also "static" pdfs. In Sphinx it is possible and relatively easy to do it automatically via LaTeX. How to automatically generate PDF out of Jekyll?
- Should we work on export Jekyll to PDF or rather work on migrating Jekyll to Sphinx?
- How often are we going to "release"? Do we even need releases? (or do we only do that for Zenodo?)
- add CodeRefinery as a community in ORCID (https://info.orcid.org/orcid-for-research-organizations/) and Zenodo (https://zenodo.org/communities/). I may be so that teh ORCID one suffices. The advantage of the CodeRefinery community on Zenodo would be that other persons can ask to have an upload included in the CR community. -> visibility for non-CR workshops but inspired of CR material.
- can existing and Zenodo-published records be added to a Zenodo community later? if yes, then we can postponing creating the Zenodo community until we already have few records there. According to https://help.zenodo.org, we can edit the metadata after the record has been published, so yes.

Conclusions:
- we want to provide pdfs
- we will only start with core lessons. Among these we can start with the lessons which are in Sphinx.
- the 3 remaining jekyll lessons will be converted to sphinx but this is not high priority and can only be done by somebody who knows both, otherwise too much work
- we start with the Sphinx lessons. if the Jekyll lessons are not converted early enough, we deposit the sources

**Thoughts/technicals:**
- We have Jekyll and Sphinx sources
- Zenodo I only want to change the title of my upload, do I still get a new DOI?
-- No, as before you can continue to edit the metadata of your upload without creating a new version of a record. You should only create a new version if you want to update the files of your record.

**Suggested lessons that we can have a go at before the open house**
with sandbox zenodo until we know how we want to do it (the pdf question)
-- https://github.com/coderefinery/word-count (~5 persons committ:ed git)
-- https://github.com/coderefinery/social-coding (~7 persons committ:ed git)

At first try it out with sandbox Zenodo for forks

-- https://github.com/johanhellsvik/word-count
seems that Zenodo does not like to assign a DOI to GitHub templates

-- https://github.com/johanhellsvik/social-coding
for this repository a sandbox DOI is created. [](https://sandbox.zenodo.org/badge/latestdoi/394669802)
Clicking its badge does however point to a non-existent dataset - is this as expected given that it was setup on sandbox Zenodo?

**Suggested lessons that we can work through and release during the open house.**
-- https://github.com/coderefinery/jupyter (~7 persons committ:ed git)
-- https://github.com/coderefinery/documentation (~14 persons committ:ed git)

# Workflow to make CR lessons citable via Zenodo
Here we fill in the needed steps. To be edited during the open house

**To do**
**The following list is copied to [staff-meeting agenda's tasks](https://hackmd.io/saJtV2axTSKgXHrD7X6JfA?both#Tasks-in-progress-or-unassigned "https://hackmd.io/saJtV2axTSKgXHrD7X6JfA?both#Tasks-in-progress-or-unassigned"). Please follow up completion status there**

- GitHub actions generation of pdfs from the lessons (JH)
- Testing CITATION.cff again (JH)
- Making sure the 3 categories we defined still then map to CITATION.cff (JH)
- Create a demo on a fork+sandbox where this is demonstrated for one lesson (JH)
- Draft email/issue to send to all contributors (RB)
- or on github issue to have it in one place
- email persons that do not respond on github issues
- create an ORCID research community (DI checks how to do it)
- create a Zenodo community and link with the ORCID one (DI checks how to do it)
- also find out whether records can be added to communities retroactively
- it seems that yes
- "communities" are edited as metadata which is editable after the release/publication as well
- Present progress on the workflow at upcoming CR staff meeting

**Preparations**
- Create and update personal ORCIDs https://orcid.org/
- Create ORCID for Code Refinery as an organization.
- Edit personal data for use .zenodo.json files. For example

    "creators": [
        {   
            "orcid": "0000-0002-1825-0097",
            "affiliation": "Feline research institute",
            "name": "Field, Gar"
        },
        {   
            "orcid": "0000-0002-1825-0097",
            "affiliation": "Feline research institute",
            "name": "Cat, Felix"
        }
    ],

- On GitHub, enable Zenodo access for the CR lessons that are to be released.

**For each lesson**

- Add a .zenodo.json to the lesson repo
- Generate pdf:s from Sphinx source via LaTeX
- In `conf.py`, set `latex_engine = 'xelatex'` (makes emojis work), then `make clean ; make latexpdf`
- This will become part of GitHub Actions, it will not be a manual step
- Create a release of the lesson on GitHub
- On Zenodo, check synching with GitHub.

**References**
- About Zenodo https://about.zenodo.org/
- Zenodo terms of use https://about.zenodo.org/terms/
- Zenodo policies https://about.zenodo.org/policies/
- Zenodo FAQ https://help.zenodo.org/
- Zenodo REST API https://developers.zenodo.org/
- Zenodo .zenodo.json and GitHub https://developers.zenodo.org/#github
- GitHub-Zenodo tutorial https://guides.github.com/activities/citable-code/
- The https://allcontributors.org/ specification and GitHub bot
- The CITATION.cff format https://citation-file-format.github.io/
- The CITATION.cff format keywords https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md
- SPDX ID short-form identifiers for FOSS license information https://spdx.dev/ids/

#
#
# Clipboard below
#
#

- Future contributions get automatically added to some meta files (https://allcontributors.org/)
- Use CITATION.cff file (see https://citation-file-format.github.io/) which is understood by Zenodo
- Alternatively add a .zenodo.json to the repo. If a .zenodo.json is present, it has presedence over the CITATION.cff.

As examples, make releases and DOI:s for a few lessons before the open house. Could be for mockup-lessons with sandbox zenodo until we know how we want to do it (the pdf question). In the mock-up add CITATION.cff file (see https://citation-file-format.github.io/), then enable this mock repo on Zenodo sandbox, then create release on GitHub (version name? any release text?). This creates a DOI.

- [x] Go through the GitHUb-Zenodo tutorial https://guides.github.com/activities/citable-code/
- [x] Check up and the advice on https://wiki.neic.no/wiki/Zenodo_howto