Feature request: Adopt Citation File Format (CITATION.cff file)

[apirogov]

There is a nice standard to express citation metadata information in a structured way for e.g. software or data publications: https://citation-file-format.github.io/

This format also has support by Github and is supported by Github-to-Zenodo pipelines:

• https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files
• https://the-turing-way.netlify.app/communication/citable/citable-cff.html
• https://docs.software-metadata.pub/en/latest/tutorials/automated-publication-with-ci.html

There are also already visual tools to help filling the file with information: https://citation-file-format.github.io/cff-initializer-javascript/#/

Also, there are tools to check its validity (e.g. usable as part of the CI): https://github.com/citation-file-format/cffconvert/tree/main/cffconvert

It would be great if the Carpentries would adopt this best-practice standard by using CITATION.cff as the way to state the citation information, instead of linking to a (possibly non-existing) plain-text CITATION file.

Ideally, all courses would have a valid CITATION.cff file and this would be part of the standard template from which a lesson is initialized.

The minimal suggestion would be to at least allow relinking the "Cite" link at the bottom to point to a CITATION.cff file.

[tobyhodges]

Thanks for suggesting this @apirogov. Indeed the idea to adopt CFF has been discussed before, and has been a goal for a while. But adoption has been delayed by questions over the best way to implement it: ideally creation and curation of a CFF would be integrated into a more general workflow for populating lesson metadata and using that information in lesson publications to Zenodo.

Here are a couple of examples of related discussions:

• Add a Lesson Credit page #238
• Enrich/Improve JSON-LD metadata for chapters and lesson #481

There have been a few threads on Slack too, I think. And although I am not currently a member I remember this was a regular topic of discussion in the Curriculum Team over the last few years as well.

The good news is that the new lesson infrastructure has made this a lot easier, by simplifying the commit history of a lesson project to make it a more accurate representation of who has contributed. But we are still some way off being able to implement a workflow for lesson publication, which would be roughly a combination of the following:

• adopting CFF
• introducing a workflow to update the CFF file, including a way for Maintainers to add authors to the CFF who are not represented in the commit history
• generating lesson metadata from a combination of info stored in the CFF, the config.yaml file, and the lesson source files (especially the episode .md files)

(Among other things the HERMES Project is being explored for this.)

So there are two things here:

1. Introducing support for CFF files where they exist in the repository, as you suggest at the end of your opening post. I know @zkamvar is juggling a number of important tasks already and faces tough choices about how to prioritise his time, but may be able to implement this before his tenure at The Carpentries comes to an end.
2. Integrating CFF files into the larger publication/annotation workflow described above, which is a bigger project.

I know the Curriculum Team has quite limited capacity to support developing any new features at the moment, but this is on the list.

Finallly, a question for you. I love the cff-init webtool and can see how it potentially solves one of the problems we face: how to make it easy and accessible for maintainers to provide and update the metadata for their lessons. However, when creating a CFF for a lesson, should we choose software or dataset for the type field?

[apirogov]

Very happy to hear that this is already being discussed! I anticipated that a proper adoption would require quite some more thought. We of course would be quite delighted to get even the basic support, to be able to "lead by example" with the "scientific metadata" incubator lesson. However its absolutely understandable that there are more pressing issues :)

The boundary can be fluid sometimes (e.g. you publish a dataset with some bits of analysis code, etc.), but in the end I would ask - how is the published entity to be used? I am not an expert / am not involved in the Citation File spec development, but to the best of my understanding, it should be classified as dataset.

• For the courses, clearly the material is the important part, which I would consider "data" - in this case, a static website is the value provided, so I'd consider it to be a dataset.

• On the other hand, if you would use CITATION.cff for releases of the Workbench packages such as sandpaper, this of course would be a software publication.

(@sdruskat can maybe chime in and correct me if I'm wrong, he's the expert both for CFF as well as HERMES 🙂 )

[sdruskat]

Hi friends 👋,

Just a quick .2ct: I agree that dataset would be the more suitable type for lessons, and agree that Workbench packages are software.

[tobyhodges]

Thanks @sdruskat and @apirogov. In terms of adopting CFF for lesson repositories, the addition of contributor roles to the CFF specification would be a huge bonus to us. I notice this is slated for inclusion in an upcoming release (citation-file-format/citation-file-format#338 & citation-file-format/citation-file-format#112). Timetables and predictions are difficult things, and I know you all have many other irons in the fire as well, but do you have any expectation for when this might be rolled out?

[sdruskat]

do you have any expectation for when this might be rolled out?

Thanks for your patience @tobyhodges! I think we're currently looking at Q1-Q2 2024 for the release of 1.3.0.

[tobyhodges]

#572 and carpentries/varnish#122 were merged today, adding minimal support for CFF to the lesson infrastructure by allowing the Cite link in the page footer to target a CITATION.cff file if one is present in the source repository. The feature will be include in the next release of sandpaper, which will be pushed out soon.

From my side, this will allow me to document the feature (carpentries/sandpaper-docs#188) and encourage people with existing lesson projects to use it (carpentries/lesson-development-training#350), and to modify the template repositories used for brand new lessons to include a template CITATION.cff file with a bunch of FIXME values (carpentries/workbench-template-md#41 & carpentries/workbench-template-rmd#65).

What else would you like to see before this issue could be closed @apirogov?

[tobyhodges]

Following up to say that the minimal CFF support described above was included in varnish v1.0.2, released today thanks to @froggleston and @ErinBecker.

[apirogov]

Sorry for the late reply, thanks a lot for the great work! From my point of view, when the remaining few issues you linked are resolved and CITATION.cff is established as the new "default" for new lessons, I'm perfectly happy and this can be closed :)

[tobyhodges]

• Document support for Citation File Format sandpaper-docs#188
• Use Citation File Format workbench-template-md#41
• Adopt Citation File Format workbench-template-rmd#65
• Update parts about citing lessons lesson-development-training#350

[tobyhodges]

All of the above have now been taken care of. I opened #583 to apply the template to sandpaper itself, so that new lessons built locally with the create_lesson() function will include the CFF file. If/when that is merged, we can close this issue and begin thinking about how we could make more use of CFFs in lessons in the future.