[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 https://github.com/ESIPFed/sweet/commit/344342fdfc9df9b04acfc23e9ff429f5e24c21a9 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 https://github.com/ESIPFed/sweet/pull/276 directly.

— Reply to this email directly, view it on GitHub https://github.com/ESIPFed/sweet/issues/256#issuecomment-1435385029, 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