what is a citation format file?

[mikofski]

Is your feature request related to a problem? Please describe.
create a citation format file: https://citation-file-format.github.io/

Describe the solution you'd like
create a citation format file: https://citation-file-format.github.io/

Describe alternatives you've considered
create a citation format file: https://citation-file-format.github.io/

Additional context
create a citation format file: https://citation-file-format.github.io/

[adriesse]

I that a question to an answer?

[mikofski]

I can't remember, but I think we need to do this?

[adriesse]

Not needed, but nice to have?

[ColmBhandal]

Hi I'm new to the repo and I just saw this, decided to learn what a cff file was and mocked one up with a Gist, taking the details of the 4 people in the org that I found on GitHub and using the CFF Initializer to get a rough CFF started. Here's the Gist:

https://gist.github.com/ColmBhandal/0751d0c05c77cb8dc30bd660470547de

[mikofski]

Thanks! Can you please copy the gist into a new pull request?

[ColmBhandal]

@mikofski I don't seem to be able to ping "@pvlib/maintainer" in the PR so I'm just pinging you here. There are two outstanding tasks on the PR which I'll need guidance with (the 3rd I believe is exclusively for maintainers). I've added a "(Maintainer please advise)" prefix to those tasks. Thanks.

[kandersolar]

Looking briefly around at other packages, CFF files are used for a few things: pointing to publications in JOSS or similar, pointing to Zenodo DOIs, or not pointing to any external reference and just being a reference in itself. I don't think the latter makes sense for us. Maybe it should just be a citation to the JOSS paper?

Also, according to this, the Zenodo integration will use the CFF file if it exists. That might not be desirable for us, as I imagine it would use the JOSS authors list in place of the full list of GitHub contributors.

[ColmBhandal]

I had a brief look at the PDF linked here. It seems as though using the CFF as a way of linking the software to a research paper is more of a secondary use case, as far as I can see from the "File structure" section:

"optionally, a list of references which should be cited in different use cases or scopes, e.g., a software paper
describing the abstract concepts of the software (references)."

To me, those references act more like the references on a research paper. The CFF is trying to be the analogue of citation metadata on a research paper. That data breaks into:

1. The data for the paper itself (journal, authors, date etc.) - so others can cite it
2. The list of references upon which that paper depends - so others can follow the trail of research backwards (and then potentially cite that too if they need to)

I guess maybe some people just pop in an empty CFF with just one or more references, but that seems like a misuse from my limited understanding of the purpose of CFF. From what I can tell, I think the CFF should have both a reference to any JOSS paper upon which PVLib is based, but also contain the metadata for the repo itself.

---

As for the authors issue - I had actually thought about that problem in the initial mockup I did of the CFF. Seems like others have encountered this problem and one solution I've seen is to use the git shortlog & a script (e.g. a Python one) to automatically update the CFF file with the list of all the contributors. See here. It's a bit messy - for example, it doesn't solve how you would sort authors according to who should be credited the most during a given release- there's a discussion on that here.

Alternatively I'm not sure if there's a way to tell downstream tools to use the GitHub contributors list in addition to the CFF for author info? But even then (and now?) you still run into the same issue of who gets credit and in what order.

[cwhanse]

If we add a CFF for the JOSS paper, and that makes it easier for people to add the reference to their bibliography, I'm in favor.

Is there any kind of "Cite This" button that could be added? E.g. https://ieeexplore.ieee.org/document/9543668

[mikofski]

@cwhanse my understanding is that if we have the CFF file in our repo, then GitHub will automatically add a Citation section to our repo main landing page like this:

(see: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files)

See: https://citation-file-format.github.io/

[ColmBhandal]

@wholmgren Per your suggestion moving the PR discussion to the issue and replying to this:

I feel like the currently proposed cff only manages to advance one of those goals, albeit an important one: give @kanderso-nrel credit.

Of the goals you listed and for the current state of the CFF (just a rough draft and subject to change) I think that may be correct, but note that @cwhanse also seems to be in favour of a follow-on issue in which a script will be generated to auto-append all contributors to the CFF using the Git shortlog - allowing the CFF to be a living thing that reflects the top contributors per release. As per discussions on the PR though, that issue would in turn have its own complications like adding the headache of CFF maintenance to the maintainers (presumably), which is still added work even with an automated helper script (unless you fully automated it but that could be difficult).

But I can think of at least one other goal. You mentioned on the previous comment:

I think the best practice is to cite the DOI generated by zenodo for the version of pvlib used in a work.

While that may be the case, if CFFs are becoming the standard way of citing GitHub repos, over Zenodo, which seems to be suggested by the accepted answer to this academia SE question, then people visiting PVLib might look for a CFF to cite the repo when they visit it, like the way people look for a README.md as the first place to read about the repo.

Note: there is also an answer on that SE referencing Zenodo, but people might see that as the "old" way of doing things.

Edit: in fact thinking about it, Zenodo's decision to automatically defer to the CFF if it's there seems to suggest that yes, the CFF is now the standard way of defining the citation metadata and Zenodo is happy to use is as the system of record.

[adriesse]

I think it's worth having a discussion about algorithms for author lists. Obviously I will never make the top 10, but it would be nice to have my name show up here or there now and then.

[ColmBhandal]

Hey @mikofski I closed that PR anyway. Your comment on the PR about future ideas made sense to me. Maybe it would be worth moving future discussions here to the issue since the PR is now closed? I fear conversations on the PR may be lost.

May I also suggest the following:

1. Rename this issue to widen the solution focus: instead of calling it "what is a citation format file?" call it something like "Figure out better citation for PVLib" (or something better than that!).
2. Update the issue description with the goals of what needs to be figured out: ensuring all collaborators are fairly credited, ensuring people cite the repo correctly, giving people a clickable link back to the repo, etc.
3. OR instead of 1 & 2 - maybe create a new issue for figuring out what to do about citation & then mention it in the description for this issue saying something like "This is paused until we figure out what we're actually doing around citation"
4. Perhaps remove the "easy" and/or "good first issue" tags? I think given all of the design/requirements considerations that have come up in the conversations that have taken place on this issue & my (now closed) PR, to me this no longer feels like something easy nor a good place to bring people who are looking to contribute for the first time (like me). It may be too overwhelming. Certainly, if down the line the maintainers all agree on a strategy for citation (e.g. via discussions on this issue) then a follow-on, clearly defined issue may be apt for a newcomer (e.g. if everyone agrees to add a CFF file, then "Add a CFF file" would be a good issue for a newcomer). That's just my feeling though as a newcomer - maybe there is some merit in still leaving one/both of the tags in there because a newcomer may have experience with this stuff... although I think "Help Wanted" should suffice there.

[mikofski]

@ColmBhandal I'm tempted to just close this issue, and reference it from a new one, as I think we've done the research and answered as least in part what a citation format file is. You were definitely right about the tags, I was so wrong! Thanks for taking this on and for helping us learn more.

[ColmBhandal]

Thank you @mikofski & team for your time and these discussions, I learned a lot!