Issues mostly about how GitHub displays 'cite this repository'

[zenorogue]

Hello, I have added CITATION.cff to our GitHub repos, but some things are not satisfying:

• "message" field seems to be a great idea, but GitHub does not display it, it just displays the default text "If you use this software in your work, please cite it using the following metadata." which does not fit.
• the conference paper and the repo are not the same (the project has changed a lot in 4 years), and I would like to suggest the readers to cite both -- with "preferred-citation" only the conference paper is produced as BibTeX, and without, only the repo (fixing the issue above would help, but showing citations to both and/or to references would help even more)
• the "pages" field in BibTeX is a page range (9--16) while in the schema it is defined as the number of pages (8), I do not see the page range
• if I set "preferred citation", the BibTeX generated by GitHub does not seem to include most of the data entered
• it is not clear what "date-released" is supposed to be (date of the original release? date of the last update?) I would expect the citer to cite a specific version, but GitHub does not show that in the generated BibTeX file

These are mostly issues about GitHub, so not sure whether I should raise them here, or somewhere at GitHub.

[jodischneider]

Often people have CONDITIONS about WHEN to cite WHICH thing, and BOTH is sometimes right. So I think there are probably a few important use cases there. I agree about the message, in my case I am using CFF for a bibliography on GitHub (it HAS machine files in it but the thing itself is not software). Besides page range, article number is increasingly used in papers.

…

On Wed, Sep 15, 2021 at 10:33 AM Zeno Rogue ***@***.***> wrote: Hello, I have added CITATION.cff to our GitHub repos, but some things are not satisfying: - "message" field seems to be a great idea, but GitHub does not display it, it just displays the default text "If you use this software in your work, please cite it using the following metadata." which does not fit. - the conference paper and the repo are not the same (the project has changed a lot in 4 years), and I would like to suggest the readers to cite both -- with "preferred-citation" only the conference paper is produced as BibTeX, and without, only the repo (fixing the issue above would help, but showing citations to both and/or to references would help even more) - the "pages" field in BibTeX is a page range (9--16) while in the schema it is defined as the number of pages (8), I do not see the page range - it is not clear what "date-released" is supposed to be (date of the original release? date of the last update?) I would expect the citer to cite a specific version, but GitHub does not show that in the generated BibTeX file These are mostly issues about GitHub, so not sure whether I should raise them here, or somewhere at GitHub. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#343>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AADVGZSNXPUG3SYZZXTAACLUCC4FZANCNFSM5ECXJM7A> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[sdruskat]

Hi @zenorogue, thanks for this issue, and sorry for the delay in replying.

You're right, all but one questions are related to the GitHub feature, not the format/schema. Pinging @arfon, who can maybe help forward your issues to the GitHub team responsible for the widget.

One clarification that I hope helps you is:

• the "pages" field in BibTeX is a page range (9--16) while in the schema it is defined as the number of pages (8), I do not see the page range

You define the page range in CFF by using start and end on the respective reference.

If you don't have any further questions regarding the format/schema, please feel free to close this issue.
You're always welcome to open another one should any questions arise in the future.

[sdruskat]

Besides page range, article number is increasingly used in papers.

Thanks, @jodischneider, for this comment. I'll add article-number to the things we should think about for a new version of CFF in a new issue.

[arfon]

Hi @zenorogue, thanks for your feedback! (I'm on GitHub staff)

"message" field seems to be a great idea, but GitHub does not display it, it just displays the default text "If you use this software in your work, please cite it using the following metadata." which does not fit.

Yes, I realize this would be desirable in many cases. We may allow this in future but for now are limiting this to the default text.

the conference paper and the repo are not the same (the project has changed a lot in 4 years), and I would like to suggest the readers to cite both -- with "preferred-citation" only the conference paper is produced as BibTeX, and without, only the repo (fixing the issue above would help, but showing citations to both and/or to references would help even more)

I understand this use case but I'm not exactly sure where this should be fixed. One option would be to optionally make preferred-citation an array/list (i.e., one or more entries), but that feels a little in conflict with the idea of the design today.

Right now, one option is to simply have a BibTeX file (i.e., not CFF) called CITATIONS.bib in the root of your repository that includes all of the BibTeX entries you'd like people to cite. The GitHub user interface won't be able to parse this file, but it will link to it.

[hainesr]

Hi @zenorogue, I am the dev who looks after ruby-cff which GitHub uses under the hood. I've only just spotted this issue, sorry, and had a couple of questions/comments:

if I set "preferred citation", the BibTeX generated by GitHub does not seem to include most of the data entered

Please could you raise an issue at ruby-cff with details of what is missing?

it is not clear what "date-released" is supposed to be (date of the original release? date of the last update?) I would expect the citer to cite a specific version, but GitHub does not show that in the generated BibTeX file

date-released is probably more relevant to software, which is where we started from with CFF after all. It would refer to the release date of the particular version you are referring to. BibTeX doesn't have a version field in any of its standard entry types so we can't expose that directly. We are looking at supporting a BibLaTeX format that does have that sort of thing. You can use date-published for paper citations which may make more sense in that context.