[INFRA] use tributors to list contributors and CITATION.cff for referencing

[Remi-Gau]

• closes [DISCUSSION] acknowledge contributors in DOIed specs on Zenodo #66
• relates to Maintainer/Steering credit on BEP papers #627

1. Add new files to becomes the single, unambiguous, authoritative representation

• the .tributors file for the list of contributors, their info and their contribution type
• the CITATION.cff file for the bids spec version and potentially other metada of the repo to be used when releasing on zenodo
• the .all-contributorsrc file for the required info to update the README contributors table

2. Add a script that uses tools/new_contributors.tsv as input and

• update .tributors
• uses .tributors to update .all-contributorsrc and CITATION.CFF

3. Add a script to update the contributors table in appendix based on .all-contributorsrc

Note that this table is now sorted alphabetically

4. The .all-contributorsrc is generated to make use all-contributors to generate a table of contributors in the README.

5. Changes little to the workflow for users to add themselves as contributors (or update their contributions): still done via the wiki, but they should now specify:

• name:
• contributions:
• email (optional):
• github (optional):
• affiliation (optional):
• orcid (optional):
• bio (optional):
• website (optional):

New contributors email should in any case be provided to the maintainers privately.

6. Before a new release, maintainers

• manually update the tools/new_contributors.tsv'
• run make update_contributors
• a script updates:
  • .tributors
  • .all-contributorsrc (the tributors package handles this),
  • README.md contributor table (the all-contributors package handle this)
  • the authors field in CITATION.cff (can be scripted but may be refactored once tributors can handle this)

TODO

• identify github username of MANY contributors
• add avatar in README for contributors that have no github account
• collect orcid numbers of contributors
• identify eventual duplicates
• ensure the final number of contributors matches the current list
• add worflow to validate CITATION.cff file
• update contributing and wiki to explain how to add oneself as a contributor / update contribution lists and for maintainers how to update those files
• move institution that contributed to the acknowledgment section of the BIDS website, see also: Initiate RF of acknowledgement to provide listing for other funders bids-website#279
• figure out how PDFs will get released
• add caveat that contributors that do not add their email addresses may effectively exclude themselves from participating in elections

---

To discuss

• This will enforce an alphabetical order of contributors on zenodo. EDIT: Steering group approved of it

[yarikoptic]

• manually update the .tributors file with new contributors

FWIW, here is the workflow @vsoch (welcome to provide feedback here) prepared for datalad where we get a PR if tributors finds something needing updating (e.g. a new contributor, updated metadata etc): https://github.com/datalad/datalad/blob/master/.github/workflows/update-contributors.yml So I guess similar setup could be done here.

identify github username of MANY contributors

FWIW, I don't think it is very reusable as-is but just an idea: here is the script I used to collate list of invitees for DataLad's JOSS paper https://github.com/datalad/datalad-git-bug-dumps/blob/master/tools/make-summaries . The point was to invite also contributors to issues (not only code contributors), so we used https://github.com/MichaelMure/git-bug (IIRC) to fetch all issues from datalad github repo (hence this large https://github.com/datalad/datalad-git-bug-dumps/blob/master/all-bugs.json ), and then populate list of invitees with aforementioned script. I don't know if there are any contributors which aren't committers in BIDS though, so might not be worth the struggle. But also it seems that git bug dump includes github logins (and names) so you could match a good portion of contributors... alternative -- just use github api to get list of all PRs and their owners, and names for those users.

[Remi-Gau]

I don't know if there are any contributors which aren't committers in BIDS though, so might not be worth the struggle.

In terms of issue openers that never commited I think we might have quite a few

But also it seems that git bug dump includes github logins (and names) so you could match a good portion of contributors... alternative -- just use github api to get list of all PRs and their owners, and names for those users.

Yup that should get me quite distance already. FLW

[sappelhoff]

Thanks @Remi-Gau -- I think this is a good initiative, also relating to some comments in #901

Do you think we'd be able to integrate contributor email addresses here as well? AFAIK we currently only have those in a sheet shared among maintainers, because we need them for the steering group elections.

[Remi-Gau]

Thought about that.

There are already some emails in the tributors file already that were caught by the tributor package when it pinged the github API to get a first list of commiters.

Before adding more however, I would like to make sure that contributors are OK having their email listed on there. Would make it more convenient for us maintainers but I am not sure that all would be OK with this.

[sappelhoff]

discussion between @Remi-Gau and me just now:

1. the BIDS specification on zenodo is just the PDF, the entry on Zenodo is created and updated manually:

   bids-specification/Release_Protocol.md

   Line 217 in 8c9fa11

   ### 10. Uploading the stable PDF to Zenodo

2. this PR was working under the assumption that Zenodo pulls the repo contents via a webhook (on release), thereby automatically parses the newly created CITATION.cff file to update the zenodo metadata, and makes the PDF available with the correct metadata
3. HOWEVER, this is not what happens (see point 1)
   1. we never commit the PDF to our repo history:

      bids-specification/Release_Protocol.md

      Line 142 in 8c9fa11

      ### 6. Get the built PDF

   2. if proceeding with this PR as is all we would get is an archive of the bids-specification repo (without PDF) and the correct metadata
   3. (but we want the PDF without the other bids-specification repo files)

Potential solutions

1. switch on zenodo for the bids-specification repo --> on release, an entry will be automatically created with correct metadata informed by the CITATION.cff from this PR
   1. in a next step, we manually upload the PDF to the other zenodo entry (as before)
   2. we copy the CITATION.cff metadata from the bids-specification record and add it to the manually created zenodo entry
   3. this is potentially laborious, but allows us to keep the present setup with minimal changes
   4. (we'd have to check exactly how laborious the copying over would be)
2. try whether dumping a CITATION.cff (from this repo at release time) together with a pdf into the manually curated zenodo entry can automatically updated the zenodo metadata (i.e., update the info without going via the github webhook)
   1. UPDATE: Remi tried, and this doesn't work: [INFRA] use tributors to list contributors and CITATION.cff for referencing #1115 (comment)
3. create a new repository under the bids-specification org called "pdf-releases" (or similar), and hook it up to zenodo. Then start putting the BIDS spec PDFs in there piece by piece, always releasing each version. For the most recent ones, start adding the version-specific CITATION.cff file in addition to the version-specific PDF (for earlier versions, just upload the PDF, as we didn't have the CITATION.cff file back then).
   1. Potentially contact zenodo on whether they can remove / redirect the old DOIs to the new ones --> but little hope for that, see their FAQ: https://help.zenodo.org/ ... for records that have existed for a long time, modifications are unlikely to be made.
   2. if zenodo doesn't help us redirect, we will have two DOIs for BIDS spec PDFs from version 1.0.0 up to 1.8.0, which is unfortunate but maybe okay.
   3. (or we only start releasing spec PDFs from the new "pdf-releases" repo starting with version 1.9 -- then each version would have one DOI, but spec versions would be scattered across two zenodo records, which isn't too great either, as each zenodo record also has a "general DOI" that points to all versions of that record, and we'd thus have two such "general bids spec pdf DOIs")

[sappelhoff]

Just a note that on the "recent contributors" WIKI, where contributors are supposed to enter their details, it currently says:

- name:
- contributions: 
- email (optional): 
- github (optional): 
- affiliation (optional): 
- orcid (optional): 
- bio (optional): 
- website (optional): 

If all details except the name is optional, we should maybe include the caveat that contributors that we don't have contact information of are effectively excluding themselves from participating in elections etc. -- and may not even be considered "active contributors" if we vote for a governance amendment that defines "active contributors" as those that:

1. have contributed AND
2. have not explicitly opted out AND
3. we have valid contact information of (email address)

see also:

• BIDS Governance amendment proposals: Up for vote in autumn 2023 #1521

EDIT: I've seen above now:

New contributors email should in any case be provided to the maintainers privately.

I agree that that's a valid and good alternative. It needs to be explicitly mentioned, however.

AND I think we should start a private repository (maintainers access only) where we store contributor emails.

[Remi-Gau]

Actually I think we need to make it clear in the wiki that if people do not want to share their contact info publicly then they can do it privately but if we do not have a valid contact info then we can't count them for the votes.

[Remi-Gau]

This is in the wiki: https://github.com/bids-standard/bids-specification/wiki/Recent-Contributors#adding-yourself-as-a-contributor

As a BIDS contributor you can get to vote during BIDS steering group elections, but the maintainers will need some contact information to reach you.

If you add your email below, it will then appear on the repository (in our .tributors and CITATION.CFF file). If you do not want your email to be made public, then you should communicate your email to the maintainers privately so they can contact you.

Let me know if you think we need more.

@sappelhoff

[sappelhoff]

Let me know if you think we need more.

I added an email they should write to (bids.maintenance+question@gmail.com, which gets redirected to anyone who has access to the account signs up for this particular "forward rule", currently only me). Other than that, it's good!

[Remi-Gau]

2. ry whether dumping a CITATION CFF (from this repo at release time) together with a pdf into the manually curated zenodo entry can automatically updated the zenodo metadata (i.e., update the info without going via the github webhook)

Not seen any info in the zenodo doc that this would work.

[Remi-Gau]

• switch on zenodo for the bids-specification repo --> on release, an entry will be automatically created with correct metadata informed by the CITATION CFF from this PR ... in a next step, when manually uploading the PDF to the other zenodo entry (as before), copy the citation cff metadata and add it to the manually created zenodo entry

Are we sure that if we do that we will keep the same generic DOI?
Should we ask zenodo in advance to see if some DOI magic needs to be done?

• try whether dumping a CITATION CFF (from this repo at release time) together with a pdf into the manually curated zenodo entry can automatically updated the zenodo metadata (i.e., update the info without going via the github webhook)

• create a new repository under bids-specification "pdf-releases", hook it up to zenodo, and start putting the BIDS spec PDFs in there piece by piece, always releasing each version. For the most recent ones, start adding the CITATION CFFs (they were not available for the earlier versions, so think of a solution for that). Potentially contact zenodo on whether they can remove / redirect the old DOIs to the new ones.

Other possibility, github allows cutting release from any branch, so we could have a branch that we just use for realeases that has only the pdf and the citation.cff for the metadata?

[sappelhoff]

Are we sure that if we do that we will keep the same generic DOI?
Should we ask zenodo in advance to see if some DOI magic needs to be done?

it will be a different "generic" DOI. With this solution, we'd have BIDS version PDFs <1.9 under one DOI and >= 1.9 under a different one (if one takes the "generic" DOI that zenodo creates for all versions of a particular project. each PDF will of course still have its own DOI). (EDIT: got confused with my solutions 3 and 1) a bids-specification zenodo project linked to GitHub from which we'll copy over the metadata to the existing bids-specification zenodo project (not linked to GitHub) that is only hosting the PDF specs. (I don't like this solution very much)

But yes, perhaps we can discuss solutions with the Zenodo team, however I am afraid that most requests we could have would be rather invasive, like: "can we cancel this project and redirect all DOIs to the new one?"

Other possibility, github allows cutting release from any branch, so we could have a branch that we just use for realeases that has only the pdf and the citation.cff for the metadata?

I would prefer having a dedicated repo for this 🤔 it seems cleaner to me and we wouldn't have to be careful if we ever wanted to archive the actual bids_specification repo content on zenodo.

---

Overall, I am in favor of my option 3 from #1115 (review)

and in a next step asking zenodo whether they'd kindly close the currently existing zenodo project (https://zenodo.org/record/7263306) and:

1. redirect the generic DOI of that project (https://doi.org/10.5281/zenodo.3686061) to our then newly created and GitHub-linked project
2. redirect the spec version specific DOIs of that project(v1.0.0 until v1.8.0) to the then newly released spec version specific DOIs (of the newly created and GitHub-linked project)

If zenodo won't cooperate on that (which would be totally understandable, as it's a huge request) -- I'd bite the bullet of having each BIDS spec PDF from version 1.0.0 until 1.8.0 accessible under two different DOIs, which is dirty ... but life is messy. In that latter, messy, case we could upload one last release to the old zenodo project which contains just a README that says: "please look at this project instead".

[Remi-Gau]

Ok most of that makes sense to me but let's see what the other maintainers have to say about this at our next meeting

[Remi-Gau]

@sappelhoff
most of the zenodo / pdf issues discovered via this PR are kinda independent, no?
so we could merge this PR and open an issue to start the discussion afresh (easier for other people's to follow).

[effigies]

so we could merge this PR and open an issue to start the discussion afresh (easier for other people's to follow).

Yes. After you left the call yesterday, we agreed that it made more sense to get this in and then test any plans in the Zenodo sandbox. I don't think anybody else has the energy to review this, and it's not spec-related, it just needs to work.

[effigies]

Make buttons turn green.

[Remi-Gau]

Make buttons turn green.

#LifeGoals