[FEATURE] add citation information via CITATION.cff

[brandonnodnarb]

see: https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-on-github/about-citation-files#about-citation-files

This topic can be discussed at the monthly ESIP STC meetings.

[brandonnodnarb]

Template should be something resembling this:

cff-version: 1.2.0
message: "Please cite SWEET thusly."
title: "Semantic Web for Earth and Environmental Terminology (SWEET)"
type: software
url: 'http://sweetontology.net'
license: CC0-1.0
version: '3.5'
date-released: '2022-07-14'
doi: #[will be available on next release; can back-propagate if needed but looks to be manual process]
authors:
      - family-names: 
        given-names: 
        email: 
        affiliation:
        orcid:

For the authors, how do we want to handle this? Do we want to list ESIP STC, or individuals? I should think we want to list individuals -- we do participate in a credit economy. If I run git shortlog -ns --since=2019-11-22 I get the following users who committed to version 3.5:

commits	user
27	brandonw
26	Lewis John McGibbney
16	Simon Cox
5	John Graybeal
4	Pier Luigi Buttigieg
3	Charles Vardeman
2	Federation of Earth Science Information Partners
2	Nicholas Car
1	Brad Hards

which I assume is a subset of what is depicted on Insights/Contributors

However, this does not capture users who created, or commented, on issues or discussions, reviewed PRs, or contributed to discussion at meetings -- STC monthly meeting and/or January and July ESIP meetings. It would certainly make sense to include these contributors as such. Unfortunately, from the cff spec document, it appears there is no valid contributor tag.

Need to investigate if there is a sane way to automatically generating contributors from the github api?

It seems we could also add the previous paper citation (Raskin and Pan, 2005) and designate one as preferred, one references the other, or perhaps to request both be used.

Anyone have recommendations or thoughts on this?

[rduerr]

I love the concept of .cff files! I hadn't heard of this before.

I do think we need to include more that just the committers to the author's list. Also, I hate using group names, as I've actually had to prove that I was a member of a group that did something and I never want to go through that again! So I hope you have luck with getting a contributors list out of the github api. If not, you could just do what the schema.org group did, which was ask folks to add themselves to a list kept in a github issue. That way, if you don't care and don't pay attention, you don't end up in the citation!

Raskin and Pan, 2005 would not be the preferred citation! In my mind this, following the ESIP endorsed convention, should be like a new edition of a book, which can have an entirely new set of authors, etc. Yup, the version number has to be part of the citation... I think it is fine to include the previous paper as part of the "reference" list for this version of the SWEET citation; but am wondering if the .cff concept includes reference lists? And if not, where should those be kept?

[brandonnodnarb]

I do think we need to include more that just the committers to the author's list.

Agreed.

you could just do what the schema.org group did, which was ask folks to add themselves to a list kept in a github issue.

This looks like the easiest option.

[brandonnodnarb]

Update

output of git shortlog -ns --all (corrected for duplicates):

commits	name(s)	handle
126	Lewis John McGibbney	@lewismc
115	brandonw (brandon 71, brandonw,40; brandonnodnarb, 4)	@brandonnodnarb
40	Simon Cox	@dr-shorthair
15	Stephen Richard	@smrgeoinfo
6	Carlos Rueda	@carueda
6	John Graybeal	@graybeal
4	Pier Luigi Buttigieg	@pbuttigieg
4	Charles Vardeman (Charles Vardeman, 3; Charles F Vardeman II, 1)	@charlesvardeman
2	Adam Shepherd	@ashepherd
2	Federation of Earth Science Information Partners	@esip , @esip-lab is this you?
2	Jan Martin Keil	@jmkeil
2	Nicholas Car	@nicholascar
2	ignazio	@ignazio1977
2	Chris Mungall (Chris Mungall, 1; cmungall, 1)	@cmungall
1	Annie B. Burgess	@esip-lab (?)
1	Brad Hards	@bradh
1	Ruth Duerr	@rduerr

The above list accounts for all committers from repository creation until today.

Anyone in the above list who would like to be acknowledged for their contribution -- e.g., included in the CITATION.cff file -- please reply to this issue using the following pattern:

authors:
      - family-names: 
        given-names:
        orcid:  [optional]
        email:  [optional]
        affiliation:  [optional]

or edit the associated PR directly.

While this circulates, @brandonnodnarb will compile a similar table of contributors -- e.g. users who have contributed to issues, reviewed PRs, etc. without actually committing to the repository.

[carueda]

Thanks, @brandonnodnarb 👍🏻

      - family-names: Rueda-Velásquez
        given-names: Carlos A.
        orcid: https://orcid.org/0000-0002-5440-0638
        affiliation: MBARI

[bradh]

I'm sure 344342f isn't worth citing...

[brandonnodnarb]

Yeah, @bradh wrong link. Apologies.

[jmkeil]

authors:
  - family-names: Keil
    given-names: "Jan Martin"
    affiliation: "Friedrich Schiller University Jena"
    orcid: "https://orcid.org/0000-0002-7733-0193"

author sounds a little bit to large compared to my few contributions, but yes, there is nothing like contributors in CITATION.cff.

[brandonnodnarb]

The following is a list of everyone who has contributed to SWEET development by adding or commenting on an issue.

authorID	comments	issues	already in Author list
@adamancer		1
@akthom	2	1
@alisonboyer	1
@angelozerr	1
@ashepherd	5	2	yes
@bethhuffer	6	1
@bradh	1	1	yes
@brandonnodnarb	132	38	yes
@brownag	1
@carueda	104	14	yes
@cbode		1
@charlesvardeman	14	10	yes
@cmungall	92	10	yes
@CommonClimate	2
@dbassendine	2
@donnadf	1
@dr-shorthair	198	34	yes
@dvaranka	2
@edshred2000	1
@emiliom	2
@ennaWilson	1	1
@esip	1		yes
@esip-lab	5		yes
@fils	1	1
@Garybc	9	6
@giraygi	1
@graybeal	130	11	yes
@gwemon	1
@hsu000001	1
@ignazio1977	10	1	yes
@JimBiardCics	2	1
@jmkeil	1	7	yes
@johnmckellar	2
@jvendetti	1
@kaiiam	5	1
@lewismc	441	74	yes
@linepouchard	8	1
@marwa811	2	1
@MichaelHuhns	2
@mpsaloha		1
@narock	4
@nicholascar	30	4	yes
@owairdhi		1
@pbuttigieg	37	6	yes
@rdowns		1
@rduerr	62	11	yes
@rrovetto	18	3
@SirkoS	10	1
@smrgeoinfo	63	17	yes
@stain	7	1
@stuchalk	1
@tbs1979	10	1
@wdduncan	18	1
@whitten	1
@xgmachina	5
@ZacharyRobbins		1

If anyone on this list would like to be added to the CITATION.cff file please reply to this issue completing the pattern above, or or edit the associated PR directly.

[Garybc]

You can add me. Garybc is gary berg-cross Gary

…

On Fri, Feb 17, 2023, 6:15 PM brandonw ***@***.***> wrote: The following is a list of everyone who has contributed to SWEET development by adding or commenting on an issue. authorID comments issues already in Author list @adamancer <https://github.com/adamancer> 1 @akthom <https://github.com/akthom> 2 1 @alisonboyer <https://github.com/alisonboyer> 1 @angelozerr <https://github.com/angelozerr> 1 @ashepherd <https://github.com/ashepherd> 5 2 yes @bethhuffer <https://github.com/bethhuffer> 6 1 @bradh <https://github.com/bradh> 1 1 yes @brandonnodnarb <https://github.com/brandonnodnarb> 132 38 yes @brownag <https://github.com/brownag> 1 @carueda <https://github.com/carueda> 104 14 yes @cbode <https://github.com/cbode> 1 @charlesvardeman <https://github.com/charlesvardeman> 14 10 yes @cmungall <https://github.com/cmungall> 92 10 yes @CommonClimate <https://github.com/CommonClimate> 2 @dbassendine <https://github.com/dbassendine> 2 @donnadf <https://github.com/donnadf> 1 @dr-shorthair <https://github.com/dr-shorthair> 198 34 yes @dvaranka <https://github.com/dvaranka> 2 @edshred2000 <https://github.com/edshred2000> 1 @emiliom <https://github.com/emiliom> 2 @ennaWilson <https://github.com/ennaWilson> 1 1 @esip <https://github.com/esip> 1 yes @esip-lab <https://github.com/esip-lab> 5 yes @fils <https://github.com/fils> 1 1 @Garybc <https://github.com/Garybc> 9 6 @giraygi <https://github.com/giraygi> 1 @graybeal <https://github.com/graybeal> 130 11 yes @gwemon <https://github.com/gwemon> 1 @hsu000001 <https://github.com/hsu000001> 1 @ignazio1977 <https://github.com/ignazio1977> 10 1 yes @JimBiardCics <https://github.com/JimBiardCics> 2 1 @jmkeil <https://github.com/jmkeil> 1 7 yes @johnmckellar <https://github.com/johnmckellar> 2 @jvendetti <https://github.com/jvendetti> 1 @kaiiam <https://github.com/kaiiam> 5 1 @lewismc <https://github.com/lewismc> 441 74 yes @linepouchard <https://github.com/linepouchard> 8 1 @marwa811 <https://github.com/marwa811> 2 1 @MichaelHuhns <https://github.com/MichaelHuhns> 2 @mpsaloha <https://github.com/mpsaloha> 1 @narock <https://github.com/narock> 4 @nicholascar <https://github.com/nicholascar> 30 4 yes @owairdhi <https://github.com/owairdhi> 1 @pbuttigieg <https://github.com/pbuttigieg> 37 6 yes @rdowns <https://github.com/rdowns> 1 @rduerr <https://github.com/rduerr> 62 11 yes @rrovetto <https://github.com/rrovetto> 18 3 @SirkoS <https://github.com/SirkoS> 10 1 @smrgeoinfo <https://github.com/smrgeoinfo> 63 17 yes @stain <https://github.com/stain> 7 1 @stuchalk 1 @tbs1979 10 1 @wdduncan 18 1 @whitten 1 @xgmachina 5 @ZacharyRobbins 1 If anyone on this list would like to be added to the CITATION.cff file please reply to this issue completing the pattern above, or or edit the associated PR <#276> directly. — Reply to this email directly, view it on GitHub <#256 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACIMQIQPGY25TJFIRZCQPTLWYABB5ANCNFSM5CTLSOQQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[lewismc]

authors:
  - family-names: McGibbney
    given-names: "Lewis John"
    affiliation: "NASA Jet Propulsion Laboratory"
    orcid: "https://orcid.org/0000-0003-2185-928X"

Thanks folks. Great to see a lot of activity 👍

[CommonClimate]

I am not sure my limited participation warrants authorship here, but in the interest of not holding things back:

authors:
  - family-names: Emile-Geay
    given-names: "Julien"
    affiliation: "University of Southern California"
    orcid: "https://orcid.org/0000-0001-5920-4751"

[kaiiam]

Hey all good initiative, however, I don't think posting a few issues or discussions merits authorship or reference. If I ever had to occasion to really contribute to SWEET I would add my details but I don't think I have, so I don't intend to. Best of luck with the project.

[rduerr]

Agreed - I don't think recording an issue should count towards authorship at all. It's reporting a problem!
However, contributing to a discussion about an issue that was resolved should count towards authorship. Can we figure out who contributed to the discussion of issues that were closed by this release?

[brandonnodnarb]

I can't say I disagree with either of you. The previous tables were largely exploratory on my part.

Proposal

Use the CITATION.cff file to cover the maximum extent of authorship for the repository from time immemorial. All the authors, which in this case would be anyone who committed to the repository, or the second table I posted, who wish to be included will be added using the 'authors' tag on the CITATION.cff file.

As the CITATION.cff standard has no 'collaborator' or 'acknowledgement' tag we will leave it at that for the time being; until the next release

For the next SWEET release (3.6) we will incorporate a more standard workflow by which the authors and collaborators are properly added to the Zenodo metadata for that version -- version 3.6, and only 3.6. This process will mint the DOI for version 3.6 with the proper metadata and citation information. At this stage we can keep the CITATION.cff file should anyone want to cite the repository, but we will add the version information (3.6) to the CITATION.cff file and specify that the latest version is the preferred citation.

The next SWEET release target is June, prior to the next ESIP meeting.
---end proposal---

Separately, I can investigate querying users who contributed to closed issues, more specifically users who contributed to issues closed due to a PR -- i.e., a change to SWEET not an issue that was closed for another reason (stale, irrelevant, etc.) When this is sorted we can discuss further additions.

[johnmckellar]

Thank you Brandon!! For my limited participation: ``` authors: - family-names: McKellar given-names: "John Lindsay" affiliation: "Geological Survey of Queensland" orcid: https://orcid.org/0000-0001-5489-9590 ``` Cheers, John

[r0sek]

authors:

• family-names: Rose
  given-names: "Kate"
  affiliation: "Mississippi State University"
  orcid: "https://orcid.org/0000-0002-8454-8481"

@r0sek