search

cf-convention / cf-conventions

AsciiDoc Source
http://cfconventions.org/cf-conventions/cf-conventions
Creative Commons Zero v1.0 Universal
87 stars 45 forks source link

Include DOI and License information in the conventions document #513

Open larsbarring opened 8 months ago

larsbarring commented 8 months ago

Title

Include DOI and License in the conventions document

Moderator

Not yet

Moderator Status Review [last updated: YYYY-MM-DD]

Not yet

Requirement Summary

In preparation of the implementation of DOIs (#127) and a Licence (io/#182) these information items should be clearly visible in the document. In a previous issue (#383 (closed)) it was a bit difficult to to tweak the "version line" of the documents. And adding even further information seems even less feasible. However the Asciidoctor system has a colophon section that turns out to be suitable. In this section various key information items about the document can be collected in a way that displays well both as html and pdf.

Technical Proposal Summary

From a text writing perspective the changes are simple, but to account for the slightly different needs of the draft and the released versions some github workflow automation is needed.

Benefits

Readers will find information about license, DOI, link to the web site, etc. collected in one place. Similarly, writers will be less constrained to difficult tweaking of the version line.

Associated pull request

514 (draft PR)

Detailed Proposal

The following screen clips show of how the html documents may look like. The layout of the pdf documents are the same, except for that the section is at its own at the top of the second page, and then the Table of Content starts at the third page.

Draft html document:

image

Released html document:

The "{doi}" will of course be replaced by the real DOI for the version:

image

JonathanGregory commented 8 months ago

Dear @larsbarring

This is excellent. Many thanks and well done on working out how to do it.

Best wishes

Jonathan

ethanrd commented 8 months ago

Yes, second on Jonathan's comments. Excellent and many thanks Lars @larsbarring!

One point for discussion ... I think we need to decide if we should encourage citation of 1) the top level DOI with version information included in the citation or 2) the version specific DOIs (could also include version information in the citation but is also implicit in the DOI).

larsbarring commented 8 months ago

Thanks @JonathanGregory and @ethanrd.

I think the draft PR pinpoints two things that needs to be addressed:

  1. Exactly the point you raise @ethanrd: how are the DOIs going to be organised (and generated). I was under the impression that there would be a separate one for each version of the conventions document (both the html and the pdf variants), and one overall that point to the website. Both these can be mentioned in the colophon section. And, a separate DOI series for the standard name tables. I think that it is useful to be able to make a distinction between the different versions of the conventions, and the standard name tables, in particular when looking back from sometime in the future.

  2. Already before introducing the enhancements that now are in the pipeline there were two separate author lists in the conventions documents alone. With the suggested colophon having a Use the following reference to cite this version of the document: there would be three. Add to that the .cff file and the zenodo.json, and we have five separate author lists. This will easily become problematic to maintain in tip-top shape.

I imagine that the 2 could be solved with some smart github workflow scripting, but I do not have the right skill set to do this. And there are still a few unsolved issues with the workflow script in the associated draft PR (hence the draft status). I think that it is a good time to call upon the Information Management and Support Team because I have reached as far as I can. Before that happens it would be good to sort out 1.

davidhassell commented 8 months ago

a separate one for each version of the conventions document (both the html and the pdf variants), and one overall that point to the website

Could we also have one overall DOI that always resolves to the latest conventions document (as is often the case fore software DOIs)? This may be already the case, but I just wanted to check.

larsbarring commented 8 months ago

Yes, indeed, I think that would be very useful to have in the website (not in the conventions document). I imagine that the colophon could show something like:

To cite the CF Conventions in general (not this particular document version) see this link: 
https://cfconventions.org/a-suitable-place

where the "a-suitable-place" would give further details including the overall DOI as well as the DOI for the current version of the conventions document.

HeinkeH commented 6 months ago

I'm a little confused about the orcids. I have sent my orcid a few years ago, but where can I check whether it has been taken over. Is there a list of authors and orcids. Please send me a link to it. Here is my orcid again: https://orcid.org/0000-0002-0131-1404 Best wishes Heinke

larsbarring commented 6 months ago

Hi Heinke, Thanks for the reminder, I have passed on this to another issue.

castelao commented 6 months ago

I'm a little confused about the orcids. I have sent my orcid a few years ago, but where can I check whether it has been taken over. Is there a list of authors and orcids. Please send me a link to it. Here is my orcid again: https://orcid.org/0000-0002-0131-1404 Best wishes Heinke

Added on #443 . @HeinkeH , please double-check your ORCID there. Thanks,

ethanrd commented 6 months ago

David wrote:

Lars wrote:

a separate one for each version of the conventions document (both the html and the pdf variants), and one overall that point to the website

Could we also have one overall DOI that always resolves to the latest conventions document (as is often the case fore software DOIs)? This may be already the case, but I just wanted to check.

I believe all GitHub/Zenodo generated DOIs will point/dereference to a Zenodo landing page; where they point/dereference is not something that can be changed. So a DOI that points to the CF website is not something that can be done through Zenodo. However, there are other fields in the Zenodo DOI metadata that can be changed/added that could be used to point to the CF web site, e.g., RelatedItem or RelatedIdentifier.

With the GitHub/Zenodo integration, once the .zenodo.json file is pushed to the main branch, the first GH release will automatically generate two DOIs: one DOI for that release and one DOI that will always point to the latest release. From there on out, each release will do two things: 1) generate a new DOI for that specific release; and 2) update the "latest release" DOI to point to the latest release.

larsbarring commented 5 months ago

Thanks for the clarification Ethan.

When thinking of it, having a DOI pointing to the website itself is not meaningful and not how DOIs are supposed to work. But having the current and version specific DOIs automatically generated should be useful.

I am not sure what the next steps are, to make any tangible progress with the associated PR, and the related question of how to unify/coordinate the different author lists (see here), I feel that I have reached as far as I can without substantial input, or taking over from here. Ping @cf-convention/info-mgmt

JonathanGregory commented 5 months ago

Two weeks ago I asked if it was OK now to merge @castelao's PR, which will implement DOIs for the conventions by Zenodo. @castelao asked the same question. No-one has objected. If no-one objects today, I will merge the PR tomorrow and thus close issue 127 - the oldest one which is outstanding - unless someone else does it before me!

In that issue, Lars noted these two outstanding matters:

  • Implement the CFF file for the website (see draft PR #507)
  • How to keep all the different author lists in sync. (see this comment)

which are the ones he's asked in this issue as well.

sadielbartholomew commented 5 months ago

I personally am happy with this to now be merged, but do have some thoughts regarding the follow-on PR CFF file aspect (namely #507, as Jonathan mentions), notably overall that we want to ensure there aren't multiple citations so that people might be confused which to use, i.e. have one canonical DOI including a per-version variant ideally - so on that note I will ask, is the intention to use the DOI created here and just reference that in the CFF citation file, or would that be a whole new DOI to cite that GitHub repository specifically (as I understand CFF files were designed for)? Apart from that question for anyone to answer, I can express my concerns about the CFF file over on that dedicated PR.

JonathanGregory commented 5 months ago

I have merged https://github.com/cf-convention/cf-conventions/pull/443, and thus closed https://github.com/cf-convention/cf-conventions/issues/127 and https://github.com/cf-convention/discuss/issues/178 as well. Thanks, Gui @castelao, for preparing the PR, and to everyone else who contributed.

The PR has created the file .zenodo.json. Have DOIs been created, as expected?

castelao commented 5 months ago

@JonathanGregory, we need to link this repository to Zenodo. @ethanrd, would you like to do it together?

JonathanGregory commented 5 months ago

I see that @ethanrd has created https://github.com/cf-convention/cf-conventions/releases/tag/DOI. What does this do?

ethanrd commented 5 months ago

Hi Jonathan,

@JonathanGregory wrote

I see that @ethanrd has created https://github.com/cf-convention/cf-conventions/releases/tag/DOI. What does this do?

Gui @castelao and I met last Friday and worked on linking the CF Conventions repository to Zenodo and then created a release called "DOI" to initiate the creation of two DOIs. The "DOI" release uses the "DOI" tag that we created, which points to the same commit as the v1.11.0 tag. (At least that was the intent, looks like it points to a different commit. I think that is OK for this initial DOI.)

The two DOIs are

We had to do a bit of manual editing of the DOI metadata but we think it is good to go now. Please take a look and see what you think. (Both the DOI links above will take you to the same Zenodo landing page which displays the CF Convention v1.11 DOI metadata. When the 1.12 release is made, the DOI ending in "7" will point to the v1.12 DOI page.)

Once we are all happy with the metadata, we can add a "How to Cite CF" page and announce more broadly. We can also add a DOI badge to the README.md file in the repo by adding the following line:

[![DOI](https://zenodo.org/badge/36864162.svg)](https://zenodo.org/doi/10.5281/zenodo.11288137)
sadielbartholomew commented 5 months ago

@ethanrd, those DOIs otherwise look great but from just a skim read I notice a few issues with the authors list, namely that Charlie Zender appears twice and there are authors missing, for example David Hassell should be on there but I don't see his name (so there could easily be others missing). Thought I should mention in case it has yet to be noticed.

ethanrd commented 5 months ago

Thanks @sadielbartholomew - I fixed the duplicate Charlie and added David. I went through the author list again and it looks complete now. We haven't added contributors to this record yet, so it is just the authors currently.

sadielbartholomew commented 5 months ago

Thanks Ethan for quickly amending that, it all seems good now.

JonathanGregory commented 5 months ago

The DOI is great to have. Thanks, Ethan and Gui.

JonathanGregory commented 2 days ago

Dear @larsbarring

It would be really good to implement this change in CF 1.12. We've agreed some time ago that it would be useful, and thank you for working out how to do it, by adding the colophon. In an earlier comment, you wrote:

  1. ... how are the DOIs going to be organised (and generated). I was under the impression that there would be a separate one for each version of the conventions document (both the html and the pdf variants), and one overall that point to the website. Both these can be mentioned in the colophon section. ... It would be good to sort [this] out.

As recorded above in this issue, the DOIs have now been defined.

  1. Already before introducing the enhancements that now are in the pipeline there were two separate author lists in the conventions documents alone. With the suggested colophon having a Use the following reference to cite this version of the document: there would be three. Add to that the .cff file and the zenodo.json, and we have five separate author lists. This will easily become problematic to maintain in tip-top shape. ... I imagine that the 2 could be solved with some smart github workflow scripting, but I do not have the right skill set to do this. And there are still a few unsolved issues with the workflow script in the associated draft PR (hence the draft status). I think that it is a good time to call upon the Information Management and Support Team because I have reached as far as I can.

Do you have time to update your PR #514 for CF 1.12? I agree with your concern about the large number of author lists. We certainly should address this, but we won't be able to before the deadline for the next release, so let's not wait for it.

Best wishes

Jonathan

larsbarring commented 2 days ago

Dear @JonathanGregory In principle I agree with you. But I have just had at look at the PR and it seems that the main work that remains is related to the github workflow .yml file. There has recently been substantial improvements and enhancements that I have difficulties to follow. Hence I will be happy to collaborate on this, will not be able to alone take this on in time for the release of 1.12.

cofinoa commented 2 days ago

This issue, relating to cf-convention/discuss#326.

To ensure that each release includes a valid DOI, the process will involve drafting, updating, and publishing a Zenodo record in synchronization with GitHub release actions. This draft workflow is currently under development in: https://github.com/cofinoa/cf-conventions/tree/zenodo-upload

[Note: it's an ongoing work and there are some missing pieces]

cofinoa commented 2 days ago

@JonathanGregory and @Lars

In the current setup, the actions in the cf-conventions repository produce two artifacts:

  1. Conventions document (in both HTML and PDF formats)
  2. Conformance document (in both HTML and PDF formats)

To clarify for the Zenodo deposition process:

Has there been prior discussion on this?
If so, could you point to any conclusions reached or considerations we should keep in mind?

JonathanGregory commented 2 days ago

Dear Antonio @cofinoa

As far I remember, we have not discussed this matter. I would suggest that both the conventions and the conformance documents should be included in the DOI, but only one format is needed, either PDF or HTML, and we don't need the source files. I suppose PDF is better for a version of record because its appearance is fixed. I expect @ethanrd and others have opinions.

Best wishes and thanks for addressing the issue

Jonathan

ethanrd commented 2 days ago

I agree with Jonathan that both documents should be included as PDF and the source is not needed.

larsbarring commented 1 day ago

Do we want the conventions document and the conformance document to have the same doi? I think that typically every document has its own doi. We can of course view the conformance document as "supplementary material" (as it often is called in journal articles). But I just checked the conventions document and there is no clear reference -- with a link (etc.) -- to the conformance document. And on the web pages only the html versions are available as links, and then on a separate web page (that is not obvious if one is not familiar with the CF web site). The conformance document, on the other hand provides a prominent and direct link to the conventions text, which is good. Can we add something similar somewhere "high up" near the beginning of the conventions document? Ideally I think these cross-links should include both the html and pdf versions. in both documents.

JonathanGregory commented 1 day ago

That's a good point, Lars, thanks. Yes, I think the conformance document is properly regarded as a supplement to the conventions, and they should share a DOI. Yes, that means we should put a link to the conformance document prominently in the conventions document. Also, I think we should put links to the latest and working versions of the conformance document on the CF home page, on the same line as the conventions document.