Make lesson citable

[samumantha]

• citation.cff added

Authors are currently ordered as they are ordered in github Contributors, only few contributors are not added as authors as they only did a typo fix or other small thing (they will still be asked if they think it is fair).

To do:

• ask lesson contributors if they are ok with (not) being an author (when citation file close to final) and ask to add orcid (if wanted)
• create release of lesson
• make pdf of lesson
• upload release and pdf to Zenodo, use CR community
• add doi from Zenodo to citation.cff
• link to citation.cff / Zenodo from lesson

To discuss:

• type: software (default) : appears for example in bibtex format -> Can only be software or dataset (https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#type) , what should it be?
• Version: Should the version start with 1.0.0 now?
• date-released: Together with version, should this be date of the current release, ie the date when the cff is added to main?
• should citation.cff be validated as part of the github action -> https://github.com/marketplace/actions/cff-validator ?
• For Zenodo DOI: in addition to pdf, we could upload a release of the lesson at current timepoint?

Resolves #269

[samumantha]

Pdf test: (using defaults with make latexpdf of Sphinx): codedocumentation.pdf

Notes (after only a quick look at it):

• cannot read svg files

Looks ok otherwise, what do you think?

[bast]

PDF looks good! The svg images we can perhaps convert during the pdf creation.

[bast]

• type: software (default) : appears for example in bibtex format -> Can only be software or dataset (https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#type) , what should it be? We could also think of contributing a new type to citation.cff?

Contributing a new type is a good idea! Until then it is probably more data than software.

• Version: Should the version start with 1.0.0 now?

I am thinking and unsure whether semantic versioning is the best thing for lessons but I don't have a better idea than v1.0.0.

• date-released: Together with version, should this be date of the current release, ie the date when the cff is added to main?

We can also mergeit to main with a date in future but the date should be the date we create the first GitHub release.

• should citation.cff be validated as part of the github action -> https://github.com/marketplace/actions/cff-validator ?

Yes. Very good idea. I have used this in other repos and it works great and adds very little build time overhead.

• For Zenodo DOI: in addition to pdf, we could upload a release of the lesson at current timepoint?

Yes, the snapshot of the repository at release time plus the PDF.

[samumantha]

• Version: True I did not think of that, could also be "[spring|autumn]YYYY" and we update version after each workshop with bigger changes to the material?
• validator integration: Should it be a new action or somehow be integrated into existing actions?

[samumantha]

More todos from comments:

• decide on title (see comments)
• add cff validator to github actions
• decide on versioning and add correct version

[bast]

• Version: True I did not think of that, could also be "[spring|autumn]YYYY" and we update version after each workshop with bigger changes to the material?
• validator integration: Should it be a new action or somehow be integrated into existing actions?

• new action - let me add it quick to this PR in few minutes
• and I recently re-learned that autumn/summer can be really confusing but the version could be YYYY-MM or YYYY-MM-DD. I will raise it on chat to get more input from others.

[bast]

upload release and pdf to Zenodo, use CR community

This started few more questions in my head:

• are we going to upload this manually or automatically via GitHub release?
• we probably also need to add a GitHub workflow that generates .zenodo.json - I am unsure whether Zenodo parses CITATION.cff on its own.
• I am unsure whether we can add to the CR community automatically somehow as part of a GitHub release

[samumantha]

Good points! Also came to my mind, but as automating would take me forever I opted for doing everything manually for now. Maybe we could do it manually first for each lesson once so that the lesson is citable (to do list item done ✔️ ) and then have a follow up task of automating it for the future?

Automating will probably add more questions also on adding new contributors as authors, ...

[johanhellsvik]

Good work! The contents of the cff file look good to me. The new title "How to document your research software" is a nice one.

[samumantha]

Dear contributors of this lesson, to the best of my abilities I have tried to identify "big enough" contributions to this lesson to give you the title of being an author of this lesson. There is no strict guidelines and if you feel that you would either like to be removed from authors or be added to authors, now is your time to speak up!

Everyone mentioned in the CITATION.cff file will also be author of the lesson in Zenodo.
No further action required if you are ok with things as they are.

@bast , @wikfeldt , @rantahar , @rkdarst , @svenvanderburg , @Sabryr , @annajiat , @blankdots , @blindij , @wmvanvliet , @luisaforozco , @johanhellsvik , @vezeli , @zbynio414 , @ingstra

[ingstra]

@samumantha Remove me, I just corrected a typo or something basic like that.

[bast]

PDF is now built as part of workflow: https://coderefinery.github.io/documentation/branch/citation/_static/lesson.pdf

My recommendation:

• merge this PR
• then we can adjust date, create release, upload to Zenodo as separate step

[samumantha]

Ok to merge from my side