Update how to cite

[sstevens2]

I'd like to update the citation link but need some advice. Curriculum Dev Team (@fmichonneau, @ErinBecker, @zkamvar), what is the best way to do this? Should I do a major release and publish with zenodo? Thanks!

[fmichonneau]

Hi Sarah, let us discuss it and we'll get back to you (in about a week).

[sstevens2]

Sounds great! Thanks!

[ErinBecker]

Thanks for this issue @sstevens2! We have another full-time team member coming on board in <2 weeks who will be focused entirely on supporting the community around the Incubator and Lab. This will be one of their first projects. Can we get back to you on this in a few weeks?

[sstevens2]

That works great for me. Thanks @ErinBecker!

I'm working on a push in the next 6 months for edits. Hoping to get the lesson more stable in the next year or so.

[tobyhodges]

Hi @sstevens2 thanks for your patience while the Curriculum Team researched and discussed this. We're working on developing more detailed recommendations and some automation around publishing and generating citation information, but I expect that to take at least another few weeks.

For now, I can give you the recommendations below. There's a lot of information here: please post back to this thread with questions. I'm figuring all this out as I go so I'd love feedback on what's confusing and what additional information we can be providing.

1. recommended format of the CITATION file

author(s)
lesson title[, version number e.g. if releasing via Zenodo-GitHub integration]
lesson pages URL
[concept DOI if releasing via Zenodo-GitHub integration]

As discussed with @jcohen02 below, if you'd like to include version info in the CITATION file before publishing via Zenodo, a tag structure yyyy.mm[a-z] e.g. 2020.09a can be used.

minimal example:

Toby Hodges, Aleksandra Nenadic, Julian Karl Bauer, Anne Foullioux, Sarah Stevens, Renato Alves
Building Websites with Jekyll and GitHub/GitLab, 2020.09a
https://carpentries-incubator.github.io/building-websites-with-jekyll-and-github-or-gitlab

Example with release published to Zenodo

Toby Hodges, Aleksandra Nenadic, Julian Karl Bauer, Anne Foullioux, Sarah Stevens, Renato Alves
Building Websites with Jekyll and GitHub/GitLab, v0.1-pre-alpha
https://carpentries-incubator.github.io/building-websites-with-jekyll-and-github-or-gitlab
10.5281/zenodo.4013386

(note that with future releases, the version number would need to change in the example CITATION file above but the DOI should remain unchanged, see below)

publishing via Zenodo

If you'd like to include a DOI in the CITATION file, you can activate the Zenodo-GitHub integration for this repository and make a new release (see steps below). For Zenodo, I'd suggest naming the release tag something like v0.1-beta (to allow for multiple beta releases before the first stable release, which would probably be best called v1.0): I went with v0.1-pre-alpha for the Jekyll lesson while I was testing out the Zenodo-GitHub integration... But the appropriate standard for tag structure is still to be determined (see discussion below).

Please note, you should include the "concept DOI" - the same one displayed in the badge provided by Zenodo - in the CITATION file. The ideal way to do it would be to include the specific version DOI in the CITATION file, but it's not currently possible to reserve DOIs on Zenodo for GitHub releases :( If you include the version tag name in the CITATION file before making the release, people should be able to find the DOI/info for that specific version after they follow the concept DOI.

Steps to publish release on Zenodo

In case you've never done the GitHub/Zenodo thing before, I include a full description of the steps below (these will go into the Curriculum Development Handbook soon).

1. (if syncing with Zenodo for the first time) log into Zenodo via GitHub; activate Zenodo integration for your GitHub account; make sure Zenodo integration has access to organizational (e.g. carpentries-incubator) repo (GitHub -> Settings -> Applications -> OAuth Applications -> Zenodo -> Organization access)
2. log into Zenodo
3. click dropdown arrow next to your account name (top right), then click "GitHub"
4. find your lesson repository and (if you're making the first release for this repository) activate Zenodo tracking by clicking the button next to the repository name
5. go to your lesson repository on GitHub
6. click "Create a new release" link under "Releases" (right)
7. give a tag, name, and (optionally) a description of the release
8. go back to Zenodo and click "Upload" (top menu)
9. click on your new release in the Zenodo upload listing
10. click "Edit" change "Upload type" to "Lesson"
11. fill in/adjust the relevant details, providing a short description of the lesson
    • under authors, remove all authors who haven't contributed to the lesson content (many more people will be listed, who contributed to The Carpentries lesson template) *
12. click "Save" and "Publish"
13. navigate back to the "GitHub" page on Zenodo (see step 2)
14. click on the badge below the name of the relevant repository (which should be at or near the top of the listing)
15. copy the Markdown snippet at in the pop-up and add this to your repostory's README.md on GitHub
    • clicking this badge button will always take users directly to the Zenodo listing of the latest release of your lesson
16. add the DOI displayed on the badge to your CITATION file *

* we hope to include ways to automate these steps in an update to the lesson template soon...

Making a new release

When making new releases of the same lesson in future (e.g. to update author list or to reflect significant updates to the material), follow steps 2-12 above and update the version number (and any other outdated information) in your CITATION file.

[jcohen02]

Hi @tobyhodges, many thanks for this information, it's very useful.

I have one question around versioning for alpha or in-progress versions of materials. If there is an early-stage version of a lesson that has been taught but is not yet ready to be archived via Zenodo (perhaps because the authors/maintainers know there are still changes to make and don't feel the lesson is ready for official release and long-term archiving in its current format), I think it would still be useful to still have some way to include a version in the CITATION file. This would ensure that if others want to teach an early-stage lesson, they can both cite exactly the version they taught, and also refer to a particular state of the material while things may still be changing and being updated.

As a result, I wonder if it might be worth considering including some sort of versioning format in your minimal example, e.g. year.month[a-z] where the letter is incremented for each significant update in that year month. This could then be represented by tagging the repository with the corresponding value.

This is just a thought - I understand that adding repository tags that are different to the existing release tag structure used for the template might confuse things so if you think this is not an ideal approach I understand but I do think some way of attaching a more "user-friendly" tag or version to identify the state of the the content at a specific commit could be useful for citing material.

[tobyhodges]

Thanks for raising this @jcohen02, that's not an aspect I'd considered.

You're right that it's reasonable to want to include version information in the CITATION file regardless of whether the lesson has been published via Zenodo yet. In particular, this will be helpful if (some of) the material is ready to be taught but the whole lesson isn't sufficiently complete for the lesson to be taught by other instructors, i.e. the lesson is in alpha state. The style of version tag your suggest is a good fit for that, and has the added benefit that the tag structure is sufficiently different to the historic version numbers of the lesson template so as to reduce confusion there. Releases going from v9.5.3 to v0.1 would look a bit odd!

I'll update the recommendation above to include your suggestion.