Make a CITATION.cff file for PyGMT

[weiji14]

Description of the desired feature

GitHub added a new feature for built-in citation support on 29 Jul 2021 (see https://github.blog/changelog/2021-07-29-enhanced-citation-support/), and we should totally add this! See tweet at https://twitter.com/natfriedman/status/1420122675813441540

For those who aren't familiar, CITATION.cff is a YAML file which is both machine and human readable containing information on how to cite a software repository. I.e. it contains the project title, authors list (with ORCID support!), DOI, version, release date, etc.

Any thoughts on whether we should add this CITATION.cff file? Vote 👍 or 👎, or leave a comment below. If we do decide to add one, probably best to just link to the Zenodo DOI until we have a proper PyGMT paper (#677). We should also decide whether to keep the 'Citing PyGMT' BibTeX at https://github.com/GenericMappingTools/pygmt/tree/v0.4.0#citing-pygmt as it is or remove it (my preference is to keep it so people see it on the PyGMT PyPI page at https://pypi.org/project/pygmt/).

References:

• https://citation-file-format.github.io/
• https://citation-file-format.github.io/cff-initializer-javascript/
• https://github.com/citation-file-format/doi2cff
• https://github.com/citation-file-format/citation-file-format
• https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-citation-files
• https://discourse.pangeo.io/t/october-13-2021-software-citation-guidance-for-geoscience-communities/1873

Are you willing to help implement and maintain this feature? Yes, but someone can give this a go too by translating the BibTeX on the main README.md

[seisman]

Before translating BibTeX to CFF, see https://twitter.com/arfon/status/1420677272927866882.

[seisman]

It seems GitHub now supports a CITATION.bib file. This is what it looks like in the matplotlib repository:

Click the "View Citation File" button will open the CITATION.bib file.

[seisman]

The GMT repository already has a "CITATION.md" file and it also works well.

[seisman]

I think we should:

• Add the BibTeX entry to the "CITATION.bib" file
• Remove the BibTeX entry in the Citing PyGMT section and add a link to the "CITATION.bib" file.
• Update the release checklist and maintainers' guide

[weiji14]

So we prefer to make a new CITATION.bib file instead of a CITATION.cff file? The .cff file allows people to copy the APA citation directly I think, but the .bib file is shorter to write.

On a semi-related note, do we want to keep the AUTHORS.md and AUTHORSHIP.md files as they are now, or consolidate them all into a CITATION file?

[maxrjones]

So we prefer to make a new CITATION.bib file instead of a CITATION.cff file? The .cff file allows people to copy the APA citation directly I think, but the .bib file is shorter to write.

I would be glad to support the decision of whoever wants to put in the effort of making the .bib or .cff file, as either would be a nice addition.

On a semi-related note, do we want to keep the AUTHORS.md and AUTHORSHIP.md files as they are now, or consolidate them all into a CITATION file?

The nice part about AUTHORS.md is that it is super easy for new contributors to add themselves and more findable than if it were in CITATION.cff or CITATION.bib. Currently, we also offer the option for people to specify that they would like to be in AUTHORS.md but not in the citation (by saying something like not included in Zenodo).

For the AUTHORSHIP.md, I do not think this needs to be in the base of the repository. We could put it in the developer documentation somewhere (maintaining or contributing or a separate page) and link from the citation and authors documents.

[michaelgrund]

So we prefer to make a new CITATION.bib file instead of a CITATION.cff file? The .cff file allows people to copy the APA citation directly I think, but the .bib file is shorter to write.

I would be glad to support the decision of whoever wants to put in the effort of making the .bib or .cff file, as either would be a nice addition.

On a semi-related note, do we want to keep the AUTHORS.md and AUTHORSHIP.md files as they are now, or consolidate them all into a CITATION file?

The nice part about AUTHORS.md is that it is super easy for new contributors to add themselves and more findable than if it were in CITATION.cff or CITATION.bib. Currently, we also offer the option for people to specify that they would like to be in AUTHORS.md but not in the citation (by saying something like not included in Zenodo).

For the AUTHORSHIP.md, I do not think this needs to be in the base of the repository. We could put it in the developer documentation somewhere (maintaining or contributing or a separate page) and link from the citation and authors documents.

Agree with @meghanrjones but I'm also fine with the suggestions of @seisman.

[seisman]

I just changed my mind and agree that the CITATION.cff file is a better option because it's easy to export the citation information in both APA or BibTeX formats.

I also agree with @meghanrjones about the AUTHORS.md and AUTHORSHIP.md.

[weiji14]

Just found this nice Pangeo Showcase Webinar "Software Citation Guidance for Geoscience Communities" at https://discourse.pangeo.io/t/october-13-2021-software-citation-guidance-for-geoscience-communities/1873. Worth a look if people have time.