Add citation info

[lan496]

This PR adds citation information in README.md . Because the synchronization between README.md and index.md will be addressed in #257, this PR just touches README.md.

[LecrisUT]

Can you put that in CITATION.cff and link the README.md to that? It will create a button to more easily add the citation.

I don't know if it will work with multiple citations so let me know.

[codecov-commenter]

Codecov Report

Patch and project coverage have no change.

Comparison is base (6f45a2b) 83.60% compared to head (9175126) 83.60%.
Report is 7 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop     #322   +/-   ##
========================================
  Coverage    83.60%   83.60%           
========================================
  Files           23       23           
  Lines         7942     7942           
========================================
  Hits          6640     6640           
  Misses        1302     1302           

Flag	Coverage Δ
c_api	76.10% <ø> (ø)
fortran_api	36.82% <ø> (ø)
python_api	80.42% <ø> (ø)
unit_tests	1.24% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[lan496]

Multiple citations do not seem to be supported: citation-file-format/citation-file-format#339

[LecrisUT]

😞 Ok, we'll just have to keep Citation.cff up to date for the latest version and add any other ones in a relevant location.

[LecrisUT]

The generated Bibtex does not seem to pull in this info:
https://github.com/lan496/spglib/tree/how-to-cite

@software{
Togo_texttt_Spglib_a_software,
author = {Togo, Atsushi and Tanaka, Isao},
title = {{$\texttt{Spglib}$: a software library for crystal symmetry search}},
url = {https://github.com/spglib/spglib}
}

Specifically the doi is not there. Maybe you can change it to cite the article specifically instead of software

[lan496]

Now, doi appears.

@misc{Togo_texttt_Spglib_a_software,
author = {Togo, Atsushi and Tanaka, Isao},
doi = {10.48550/arXiv.1808.01590},
title = {{$\texttt{Spglib}$: a software library for crystal symmetry search}},
url = {https://github.com/spglib/spglib}
}

[LecrisUT]

How does it look when you try preferred-citation and refeerences?

[lan496]

references looks to refer to others' works. So, I think it does not suit the purpose.
https://github.com/citation-file-format/citation-file-format/blob/main/schema-guide.md#references
Actually, although I realize it is a practice to include CITATION.cff, I do not see its benefit for scientific OSS so much 😕

[LecrisUT]

It's mostly a convenience tool for the users to get the recommended citation. There are metadata that can be scrapped from dependencies, but it is mostly helpful to get the most recent paper about the scientific details.

[lan496]

@LecrisUT I wonder why CITATION.cff does not assume a repository may have several papers to be cited...

@atztogo To be sure, can you check this PR? I'll write a release note for v2.1.0 after this PR is merged.

[LecrisUT]

I think because papers are not a good representation of the software than can change throughout the process, while a link to the repository is always representative. My understanding of references field is that it gives additional references for the repo code, and contrary to the upstream documentation, I think it is more intuitive to add the relevant citations there.

[lan496]

Thank you for your comment. Come to think of it, references may be a place to give additional publications for the repository.
I tried to include the references section, but it does not seem to show the section in GitHub.

[lan496]

Then, I think it is beneficial to write preferred-citation in CITATION.cff but other references in CITATION.cff will not be consulted because YAML format is not common to refer to a publication.

[LecrisUT]

Hmm, thanks for checking. I think we should just let it cite only one paper or the software itself. The issue with citing the software is that I am not sure if it is picked up by the citation crawlers like "Semantic Scholar". I would leave it to you guys to decide if it should track and cite the most recent paper or the original one.

[lan496]

An identical doi for spglib software (by for example zenado) may be more appropriate for metadata purposes.

[LecrisUT]

I have been reading about the github actions around it and I find it fascinating. Best one I've seen so far is:
https://github.com/kykrueger/zenodo-publish with https://github.com/kykrueger/zenodo-new-version.

A workflow I am considering is:

• on major or minor tag, publish (the current draft) to zenodo (with the reserved doi)
• after release create a new zenodo draft, reserve a doi and replace it in CITATION.cff (think of it as pointing to develop until a major/minor tag is pushed)

I think we can do the same with CHANGELOG.md where we mark the top one as Current Version and after a release we date it with the tag name and version, clearing the Current Version section.

[atztogo]

Thanks @lan496. README.md looks good to me.

[lan496]

@LecrisUT the workflow for CHANGELOG.md looks too exaggerated for me, but let's open another issue for zenodo.