Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Include DOI and License information in the conventions document #513

Closed
larsbarring opened this issue Mar 11, 2024 · 49 comments · Fixed by #570
Closed

Include DOI and License information in the conventions document #513

larsbarring opened this issue Mar 11, 2024 · 49 comments · Fixed by #570
Labels
change agreed Issue accepted for inclusion in the next version and closed enhancement Proposals to add new capabilities, improve existing ones in the conventions, improve style or format
Milestone

Comments

@larsbarring
Copy link
Contributor

larsbarring commented Mar 11, 2024

This issue was concluded with PR #570

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

@larsbarring larsbarring added the enhancement Proposals to add new capabilities, improve existing ones in the conventions, improve style or format label Mar 11, 2024
@JonathanGregory
Copy link
Contributor

Dear @larsbarring

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

Best wishes

Jonathan

@ethanrd
Copy link
Member

ethanrd commented Mar 11, 2024

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
Copy link
Contributor Author

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
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link

HeinkeH commented Apr 30, 2024

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
Copy link
Contributor Author

larsbarring commented Apr 30, 2024

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

@castelao
Copy link
Member

castelao commented May 4, 2024

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
Copy link
Member

ethanrd commented May 13, 2024

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
Copy link
Contributor Author

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
Copy link
Contributor

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
Copy link
Member

sadielbartholomew commented May 14, 2024

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
Copy link
Contributor

I have merged #443, and thus closed #127 and cf-convention/discuss#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
Copy link
Member

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

@JonathanGregory
Copy link
Contributor

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

@ethanrd
Copy link
Member

ethanrd commented May 29, 2024

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
Copy link
Member

@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
Copy link
Member

ethanrd commented May 30, 2024

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
Copy link
Member

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

@JonathanGregory
Copy link
Contributor

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

@JonathanGregory JonathanGregory added the CF1.12? We might conclude this issue in time for CF1.12 label Oct 20, 2024
@JonathanGregory
Copy link
Contributor

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

@JonathanGregory JonathanGregory linked a pull request Nov 6, 2024 that will close this issue
4 tasks
@larsbarring
Copy link
Contributor Author

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
Copy link
Contributor

cofinoa commented Nov 7, 2024

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
Copy link
Contributor

cofinoa commented Nov 7, 2024

@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:

  • What is expected to be published in the Zenodo record?
    • Should both documents (conventions and conformance) be included in all formats (HTML and PDF)?
    • Should the source files also be included in the Zenodo deposition?
    • Or is the expectation just to publish the conventions document in PDF format?

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

@JonathanGregory
Copy link
Contributor

Dear Antonio

Thanks for doing this work.

Regarding (1), I would say that we should not list the contributors at the top, because (a) we don't list them in the conventions document itself, (b) if we show that list, we ought to add more lists as well, probably the info mgmt team, and all the previous members. This is too much, I feel. To give them more prominence, I suggest that we amend the statement, "See https://cfconventions.org for further information", which is on the front page of the PDF, to "See https://cfconventions.org for lists of contributors and other information."

Regarding (3), I continue to think that the conformance document PDF should be included in the DOI as well, because it provides an alternative and practical summary of the essentials.

Best wishes

Jonathan

@ethanrd
Copy link
Member

ethanrd commented Nov 12, 2024

I wanted to address two topics that came up in other conversations/meetings and I don't think have been raised in this issue. The first was who should be listed as the "Publisher" in the DOI metadata. The second topic is which copies of the CF documents should be considered the primary copies.

I think the primary reason for creating CF DOIs was to support citations. Having a long-term archived copy of the documents is a big plus but I don't think the archive copy should be considered the primary copy. I also don't think we should allow the fact that the CF DOI URL takes us to the Zenodo landing page to change the notion that the CF website and the documents on that site are the primary entry point users will be using to engage with CF.

So, even though "Zenodo" is the default value for publisher when minting a DOI in Zenodo, I think "CF Community" should be listed as the publisher of the CF documents and Zenodo should be thought of as the document archiving and DOI minting service/platform.

Even with the website treated as primary, some people will follow the CF DOI URLs and end up on Zenodo landing pages. To ensure that people can get to the CF website from the Zenodo landing pages, the CF DOI metadata could contain several entries in the Alternate Identifier and Related Work fields which get listed on the Zenodo landing pages. The CF 1.11 DOI metadata uses those fields to include reference to the CF website and the 1.11 conventions document (PDF). That could be expanded to reference both the PDF and HTML versions and perhaps a few other things.

@larsbarring
Copy link
Contributor Author

The sandbox webpage begins with the List of authors and then the abstract, after which the actual document is displayed in a frame. Is the abstract somehow automatically extracted from the document and placed in this position or is that manually done when designing the sandbox page?

I am asking because I think that in the webpage abstract text it would be relevant to have link to the CF website. And if the text is automatically extracted from the document I think it would be good to update the conventions document abstract to make a reference to the cf webpage.

@JonathanGregory
Copy link
Contributor

I agree with all the above points of @ethanrd and @larsbarring. Thanks.

@cofinoa
Copy link
Contributor

cofinoa commented Nov 12, 2024

@larsbarring

No, the abstract is not automatically extracted from the document. It comes from the description metadata entry, which I copied manually from the document’s abstract, with link references removed.

We can adjust the description metadata entry to include a link to the CF Conventions webpage, or update it in any way that’s more convenient for us.

Note: Once a record is published in Zenodo, the metadata can still be edited and updated. However, the uploaded files (the deposits themselves) cannot be changed. I mention this as it’s useful to keep in mind that metadata remains flexible, allowing for updates as needed.

Note 2: I'm generating new records in Zenodo's Sandbox taking into account @larsbarring, @ethanrd, @JonathanGregory comments.

@cofinoa
Copy link
Contributor

cofinoa commented Nov 13, 2024

I’ve created a new record with two versions and added it to the CF Metadata Conventions - SANDBOX Zenodo community.

The link to the new record for version 1.11 is:

Updates Made

  1. @JonathanGregory I have removed the contributors’ entries.
  2. Both PDF artifacts have been added: cf-conventions.pdf and conformance.pdf, with cf-conventions.pdf set as the default preview.
  3. @ethanrd I’ve updated the publisher entry to "CF Community."
  4. References to “related works” have been included.
  5. The names have been updated to correctly capture both Family and Given names.
  6. I created a new version from the 1.11 record to upload artifacts for Version 1.0: https://sandbox.zenodo.org/records/130532
    1. Note: The conformance artifact in Version 1.0 has a different file name and format (HTML).
    2. Authors, publication date, and related works have also been adapted for this version.

Ongoing/Pending Actions

  1. I can update the description on Zenodo’s landing page, as suggested by @larsbarring. Please provide a sample if possible.
  2. I’m working to build a version 1.12 release candidate that includes the DOI, appropriate reference style, and license in the colophon section, based on PR Include DOI and License information in the conventions document #513 by @larsbarring.
  3. This 1.12 release candidate will serve as the starting point to update the GitHub Actions workflow and draft the Zenodo publication process.

Please, your reviews and comments are important as I continue to make progress.

@JonathanGregory
Copy link
Contributor

JonathanGregory commented Nov 13, 2024

Dear Antonio @cofinoa

Thanks for the good progress and for working on the colophon of the document as well. The new Zenodo page looks good to me.

I suggest the text "See https://cfconventions.org for lists of contributors and other information about CF." to appear at the end of the Zenodo abstract. I propose this also as a new version of the statement which appears on the first page of the conventions document ("See https://cfconventions.org for further information"). Since we have it in that prominent position, I don't think we need to add it to the abstract of the conventions document as well.

Best wishes

Jonathan

@larsbarring
Copy link
Contributor Author

larsbarring commented Nov 14, 2024

Hi Antonio @cofinoa

Thanks a lot for your impressive work!!

I think that the overall layout of the sandbox page looks fine! Here are a few specific/detailed comments:

  1. Towards the bottom, there is the section "Related work:" listing the CF website as Document. If you are free to change this at will perhaps something like "Publisher's website" or similar would be better. If you on the other hand only can choose from a set list, is there another category that might fit better?

  2. The next line(s) Is identical to is perfect.

  3. Next line again Is supplement to I think we should omit, because in my opinion it would be better to direct the interested reader to the CF website and from there find out about links to the document source code and the surrounding github machinery of discussion, issues and PRs.

  4. The same as in 3. goes for the "right column" External Resources / Available in.

  5. Because this is indexed in OpenAIRE (which I have not come across before) I think that it might useful to include a link to the CF website in the abstract. If OpenAIRE indexes the zenodo abstract (probably) then Jonathan's suggestion solves this, but if the actual document abstract is indexed I think the link should be included therein. What do you think @JonathanGregory?

Finally, I fully second Jonathan's suggestion to not have the other contributors listed on the zenodo page.

@JonathanGregory
Copy link
Contributor

I agree with @larsbarring that we should put "See https://cfconventions.org for lists of contributors and other information about CF" at the end of the Abstract in the CF document if, but only if, OpenAIRE copies the document abstract, not the Zenodo abstract. If it copies the Zenodo abstract, it's sufficient to put it in that one. Thanks again, Antonio.

@cofinoa
Copy link
Contributor

cofinoa commented Nov 14, 2024

@larsbarring

Regarding the "related works" entries, they require a controlled vocabulary for the relation field. The available options are:

isCitedBy, cites, isSupplementTo, isSupplementedBy, isContinuedBy, continues, isDescribedBy, describes, hasMetadata, isMetadataFor, isNewVersionOf, isPreviousVersionOf, isPartOf, hasPart, isReferencedBy, references, isDocumentedBy, documents, isCompiledBy, compiles, isVariantFormOf, isOriginalFormOf, isIdenticalTo, isAlternateIdentifier, isReviewedBy, reviews, isDerivedFrom, isSourceOf, requires, isRequiredBy, isObsoletedBy, obsoletes.

However, I'm not entirely sure about the semantics of many of these terms. @ethanrd, do you have any recommendations on selecting the most appropriate relation values?

@JonathanGregory, regarding the abstract in OpenAIRE, I believe its content is also sourced from the description metadata entry in Zenodo. I'll make sure to include it there.

I have already made a first draft to include the colophon page and document header attributes. It's still ongoing, but you can check the current status of the PDF and HTML documents at my forked GitHub Pages site:
https://cofinoa.github.io/cf-conventions/

I have incorporated some of the content from @larsbarring's PR #514. See commit cofinoa/cf-conventions@b30c3266.

@ethanrd I have also included the CITATION.cff file to render citation info in the GitHub repository, which you drafted in PR #507, and I completed the metadata: cofinoa/cf-conventions@b724218

@cofinoa
Copy link
Contributor

cofinoa commented Nov 14, 2024

FYI, here is a screenshot of the title page and colophon page in the PDF document artifact:

image

And here is another screenshot showing the HTML format:

image

Please note that these correspond to the draft version.

@larsbarring
Copy link
Contributor Author

larsbarring commented Nov 14, 2024

@cofinoa This looks good !! Thanks for moving the Colophon idea towards completion.

  • For the draft version, is there a way to not include the citation at all?
  • Regarding the relation field, would maybe isDescribedByor is DocumentedBy be useful alternatives for the CF website (I'm guessing here) .
  • When you mentioned the CITATION.cff file, I realised that I made myself a victim of the multiple author lists problem by being inconsistent. In both the .zenodo.json and CITATION.cff could you change my affiiation to simply read "SMHI".

@JonathanGregory
Copy link
Contributor

Marvellous. Thanks, @cofinoa. A small textual point. I would say, "... version 1.12 has no DOI yet." or "... version 1.12 has not yet had a DOI assigned." or "... version 1.12 has not yet been assigned a DOI." or "No DOI has yet been assigned to ... version 1.12." Also, if you want to include "draft", I think it should be "draft version 1.12" or "version 1.12-draft", but I don't think "draft" is really necessary in that sentence. Then in the final sentence,

DON’T use the following reference to cite this version of the document, as it is only shown as a draft:
Eaton, B., Gregory, J., Drach, B., Taylor, K., Hankin, S. et al. (2023). NetCDF Climate and Forecast (CF) Metadata Conventions (1.12 draft). CF Community. https://doi.org/10.5072/zenodo.130529

it seems odd to give a DOI which looks genuine, having just said that there isn't a DOI yet. Could you put something meaningless instead, to avoid confusion e.g. zenodo.XXXXXX?

@larsbarring
Copy link
Contributor Author

Antonio, @cofinoa. I have just added a couple of technical comments in the PR. And just to clarify for myself, the draft versions will not go into zenodo?

@ethanrd
Copy link
Member

ethanrd commented Nov 18, 2024

Thanks for all your work on this Antonio @cofinoa! It looks great!

I agree, the semantics of the "related works" terms can be confusing. I find some of the terms hard to differentiate (e.g., describe vs document) and I am often pausing to decide which direction the relationship applies. I find some of the DataCite documentation useful (I believe the Zenodo metadata is derived from DataCite). Here are two snippets from those docs:

"Description of the relationship of the resource being registered (A) and the related resource (B)."

  • From relationType section. (There are definitions of the terms here as well but most are just expanding the terms into sentences. At least they specify A and B.)
relationType Interpretation Equivalent to
IsDerivedFrom A is derived from B B is source of A
IsSourceOf A is source of B B is derived from A
  • From the table in "Summary of all relationTypes" section.

I agree with Lars @larsbarring that either isDescribedBy or isDocumentedBy would be a good fit for the CF web site. I lean a bit towards isDocumentedBy.

I think the best fit for the version tag in the GitHub repo would be isDerivedFrom.

@cofinoa
Copy link
Contributor

cofinoa commented Nov 18, 2024

@larsbarring No, the draft versions are not going to be published to Zenodo.

I’m currently testing the publishing infrastructure, including GitHub for drafts, release candidates, and final releases, as well as its integration with Zenodo. This technical testing includes pre-reserving the DOI before draft publishing, drafting the upload to Zenodo for a final human-supervised review and publishing, and minting and updating the DOI in the GitHub repository. Additionally, this process involves updating the colophon section and the CITATION.cff file to ensure accurate citation information.

Once the testing is complete, I plan to propose this process in this issue for comments and review.

@JonathanGregory
Copy link
Contributor

JonathanGregory commented Nov 28, 2024

Dear Antonio @cofinoa et al.

@davidhassell is planning to create CF 1.12 next week. He and I discussed this issue in connection with that. I believe he's going to talk to you too.

It may be simpler to do the publication on the website first, followed by Zenodo. It would be good to have the "How to cite" statement in the document that David builds, including the DOI for CF 1.12, which you mention can be reserved. That's part of your PR #570.

David and I also discussed a question related to one Lars asked in your PR. Should the general CF DOI also be in the document? It might be logical to put that one the same line that refers the reader to the website for further info about CF.

In the PR, Lars has commented too on the unbreakable spaces in the list of authors. I think he's right that they're useful to stop individual authors from being cut in half by a linebreak.

Best wishes and thanks

Jonathan

@cofinoa
Copy link
Contributor

cofinoa commented Nov 29, 2024

@JonathanGregory

Yes, the PR #568 has consumed more time than expected because it is a part of the build and publish process. However, I am now finalizing the changes in the colophon and making one last adjustment to the authors section—ensuring no line break appears between the first and last names. This will leave us well-prepared for the release of version 1.12.

DOI Considerations for Version 1.12

  • For this release, I don’t anticipate including a DOI specific to version 1.12 in the colophon.
  • Instead, we’ll simplify and point to the DOI for the generic version, which should cover the necessary references.
  • While technically feasible to pre-reserve and include the DOI for version 1.12 in the colophon, the broader work required to manage DOI updates for previous versions makes this a longer-term goal.

Future Work for Next Release (i.e. 1.13)

To better handle version-specific DOIs moving forward:

  1. Pre-publish All Previous Versions:
    • Ensure all prior versions are properly published on platforms like Zenodo with their respective DOIs.
  2. Automate Metadata Updates:
    • Streamline the process of updating repository files (e.g., zenodo.json, CITATION.cff) with the relevant DOI metadata.
  3. Integrate DOIs into the Colophon:
    • Include a system to dynamically generate or update colophon information with both the generic and specific DOIs for the version being released.
  4. Review the Process with Info Management:
    • This workflow needs to be presented to the @cf-convention/info-mgmt to ensure the process is clear, reviewed, and aligned with best practices.

Next Steps for Version 1.12

I will coordinate with @davidhassell on this final step to ensure version 1.12 is reviewed and ready for publication by next week.

Let me know if you have additional thoughts or priorities for this release or the next steps!

@cofinoa
Copy link
Contributor

cofinoa commented Dec 2, 2024

@JonathanGregory, @larsbarring

I have considered your suggestions for the colophon section, unbreakable spaces, the "DOI" text and URL, and updated @larsbarring's affiliation in the .zenodo.json, CITATION.cff, and the doc "Authors" section.

I have generated a preview from this branch with the final tag. Please take a look at:
https://cofinoa.github.io/cf-conventions/final-preview/add-colophon-doi-citation/

@ethanrd I have updated the relations in the zenodo.json, but I haven't yet updated them in the Zenodo's record

NOTE: The DOI in the FINAL tag is still temporal with the FFFFFF placeholder to be replaced during the process to release the final document.

Before merging, please review and suggest any further changes. Once approved, we can proceed with releasing the final version.

Screenshots:

PDF Document:
image

HTML Document:
image

P.S: Edited to fix the version text in the colophon

@JonathanGregory
Copy link
Contributor

Dear Antonio @cofinoa

Sorry for not replying sooner. I have been too busy in the last few days. It looks perfect to me. Congratulations on getting all those things sorted out, including the Public Domain logo. See you soon at the info-mgt meeting.

Best wishes

Jonathan

@JonathanGregory JonathanGregory linked a pull request Dec 3, 2024 that will close this issue
3 tasks
@JonathanGregory JonathanGregory added change agreed Issue accepted for inclusion in the next version and closed and removed CF1.12? We might conclude this issue in time for CF1.12 labels Dec 3, 2024
@JonathanGregory JonathanGregory added this to the 1.12 milestone Dec 3, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
change agreed Issue accepted for inclusion in the next version and closed enhancement Proposals to add new capabilities, improve existing ones in the conventions, improve style or format
Projects
None yet
Development

Successfully merging a pull request may close this issue.

8 participants