algorithm-archive
algorithm-archive copied to clipboard
algorithm-archivists
Add CITATION.cff
To help visualise #848 I've created a branch with a sample file. The idea is to keep modifying it (by me and maintainers directly) until we're satisfied. But because of the visual aspect, we need a place to see what it looks like/generates. All other contributors can open up PRs on my branch to suggest changes.
You can just view the result on https://github.com/ShadowMitia/algorithm-archive/tree/citation-file
The file documentation is here for those interested https://github.com/citation-file-format/citation-file-format/blob/1.1.0/README.md#identifier-objects
I think it looks good. Of course, every maintainer (definitely) and contributor (maybe) that wants to be cited should have a chance to have their name in the file. (Yes, I want my name in there). I think there should be another message, but that's still editable, of course
I'm looking into the format for that. From what I understand there are two places we can have maintainers/contributors:
- as authors obviously, but it might break software or sites? (Especially when it reaches hundreds of contributors).
- in the
referencessection, we can sort of have a contributor list? But then that list doesn't show up on the github stuff and probs not in the citation
The references section has a lot of useful things for us I think. But I have NO IDEA how they show up in practice. But if I understand it correctly we could reference a lot of things association with AAA, including papers and contributors.
Maintainers and contributors who have a substantial amount of code in there should probably be listed as authors if they want. Let's say at least 10 PRs merged for a reasonable-ish cut-off point. I think maintainers who have less than those 10 PRs should still be included as authors if they have over 5 PRs merged. However, that is still an estimate that I don't know the scope of.
After checking, the references section is basically for dependencies, so it's not really relevant for us, at least the way I understand it.
By the way, I should probably edit the CONTRIBUTORS.md file if I want my name in your file :sweat_smile:
Well technicallyt the website code is a dependency for the actual website :grin: It's probably not the best, but the other solution it seems is a huge list of authors. I can try it just to see what it does x)
Depending on how we finalise this file, it could replace CONTRIBUTORS.md completely.
This format has a validation tool with it. I would suggest adding the corresponding github action for it, or just ask people to run the validation before submitting a new version.
One thing I'm not sure about, it considers that this repo is hosting something of type software (the other possible value being dataset). I think it's fine as is, but maybe it's not the correct way of describing this content?
If it is not the correct way, we can use the references section to more properly describe everything. But I'm not familiar enough with academic citations to understand all the subtleties :grin: :sweat_smile:
I think we're close to a first verison, so undrafting it. I'll clean up all the commits into one once all the reviewing is done (and don't hesitate on reminding me :grin: )
I never thought about asking permissions :sweat_smile: I put everyone there, mainly as a good source to try out the limits of the file. We should contact everyone, but what do we do if someone doesn't answer for example?
If we have to ask for approval maybe I should empty all the names and everyone adds themselves again?
If we have to ask for approval maybe I should empty all the names and everyone adds themselves again?
That is probably the best idea, even if that can become quite messy indeed.
I'm looking at the citations.cff repo. I'll probably raise an issue about citing a ressource or website instead of just software and dataset, and see what they recommend.
I'm listing a coupe of issues in the meantime that might be interesting:
- https://github.com/citation-file-format/citation-file-format/issues/66
- https://github.com/citation-file-format/citation-file-format/issues/112
- https://github.com/citation-file-format/citation-file-format/issues/329
I forgot to put a message here, but I've opened an issue over there to ask for advice/evolution for citing a website/book
https://github.com/citation-file-format/citation-file-format/issues/358
To the discussion about what to do with people who do not want to be cited, here's a few solutions:
- Only put people in the Citation.cff file if they have ORCID id's. This trims down the author list and makes sure that people who need citations get the citations. It also ensures that people using the AAA for academic work can contact other academics. Everyone else can be in a more readily available contributor's chapter in the AAA, maybe something like this: https://github.com/all-contributors/all-contributors
- Have different tiers of contributions. The Citation.cff file could be used for people who have contributed a "significant amount" to the AAA. It's a bit hard to figure out what significant means here, but it's an idea. We could use the dev team, maybe? Again, we need a better contributor's file here as well.
- Just have everyone who opts in to be in the citation file
In all the cases, the citation file should be opt-in, in my opinion. Also: for 1 and 2, we need a way to cite "everyone else" and link to the right page, so maybe a ORCID for the AAA organization?
Heavy agree on those who have an orcid and have them self add. Those who care about it would need to do it in a PR if they aren’t a maintainer and we would be able to approve based on past work. The orcid limitation wouldn't really be a problem as I personally made one as did @Amaras to make sure we would appear.
I've heard zenodo mentionned several times, this looks like this could be relevant https://guides.github.com/activities/citable-code/
I was mentioning zenodo because it looks like this file creates a zenodo link. I am not sure if that link continually changes with each commit, though
I don't know about each commit but from citation-file:
When you publish your software on Zenodo via the GitHub-Zenodo integration, they will use the metadata from your CITATION.cff file.
(Should've added that sorry :sweat_smile:)
I got a response. The CITATION.cff file is only designed for citing software and datasets. Maybe we could use references inside to point to all the resources of the AAA (site, papers, etc).
There might be something to do with prefered-citation which I'm looking into.
The other solution is to have a bibtex directly in the project. It won't be parsed by github, but it will still show up on the right for quick access. But won't autogenerate anything.
I would say we are software and we can start versioning on every commit to master?
We are software, but the thing we went to cite is the content in that software. It works as a workaround, but it's still not 100% what the citation file is designed for.
I've added a small CITATION.bib for reference. This would get picked up by github but would only point to that file.
Right on it’s not what it’s designed for but I figure it’s better than nothing? I would prefer we use the cff a bit loosely as they are still releasing new versions that a bib that’s not very flexible
Oh wait hang on, there is a section on github on how to use CITATION.cff for other things : https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files#citing-something-other-than-software....
So actually we should be good to go on CITATION.cff. It probably won't show up perfectly inside github, but then we can get zelendo and zenodo integrations, and that should work fine.
So the only real remaining question is : what do we do about authors/contributors for the citation?
Do we only stick to authors? (And who counts as one)
Do we need to have all the contributors in the file, or do we only cite them as "Contributors of AAA" or something?
If we want them in the citation, until we get a contributor tag, do we put them as authors or do we put them in a reference section somewhere?
Let me know if I'm missing anything else.
I will answer the above based on my opinions but I think the ultimate answer falls to @leios
Do we only stick to authors? (And who counts as one)
Add All existing people from the contributors.md to the list. Ping them all in one big notification on this repo and give them a week to opt out.
Do we only stick to authors? (And who counts as one)
Until we define what an author is, I feel it is unfair to exclude people
Do we need to have all the contributors in the file, or do we only cite them as "Contributors of AAA" or something?
This replaces the contributers.md in my mind
If we want them in the citation, until we get a contributor tag, do we put them as authors or do we put them in a reference section somewhere?
Add them as authors for now, ranked by contribution count. Possibly with maintainers first (selfishly, this is because I wouldn't likely be cited and would be in the et. others. If this isn't a priority, I don't mind being near the bottom)
Do we only stick to authors? (And who counts as one)
Add All existing people from the contributors.md to the list. Ping them all in one big notification on this repo and give them a week to opt out.
I don't feel right making this list opt-out, since I assume consent is not given by default (it *could" be opt-out for maintainers and "authors" once we define that term though)
Do we only stick to authors? (And who counts as one)
Until we define what an author is, I feel it is unfair to exclude people
It feels unfair to exclude people, but it also feels unfair that we "forcefully" include inactive people who don't read their GH notifications.
Do we need to have all the contributors in the file, or do we only cite them as "Contributors of AAA" or something?
This replaces the contributers.md in my mind
Same for me.
If we want them in the citation, until we get a contributor tag, do we put them as authors or do we put them in a reference section somewhere?
Add them as authors for now, ranked by contribution count. Possibly with maintainers first (selfishly, this is because I wouldn't likely be cited and would be in the et. others. If this isn't a priority, I don't mind being near the bottom)
+1 on that: Leios first, then other optionally maintainers ranked by contributions, then authors tanked by contributions. With a possibility to move down on demand, of course
Do we only stick to authors? (And who counts as one)
Add All existing people from the contributors.md to the list. Ping them all in one big notification on this repo and give them a week to opt out.
I don't feel right making this list opt-out, since I assume consent is not given by default (it *could" be opt-out for maintainers and "authors" once we define that term though)
I am in camp opt-out.
Do we only stick to authors? (And who counts as one)
Until we define what an author is, I feel it is unfair to exclude people
It feels unfair to exclude people, but it also feels unfair that we "forcefully" include inactive people who don't read their GH notifications.
Do we need to have all the contributors in the file, or do we only cite them as "Contributors of AAA" or something?
This replaces the contributers.md in my mind
Same for me.
Authors are those in CONTRIBUTORS.md, and this replaces that file.
If we want them in the citation, until we get a contributor tag, do we put them as authors or do we put them in a reference section somewhere?
Add them as authors for now, ranked by contribution count. Possibly with maintainers first (selfishly, this is because I wouldn't likely be cited and would be in the et. others. If this isn't a priority, I don't mind being near the bottom)
+1 on that: Leios first, then other optionally maintainers ranked by contributions, then authors tanked by contributions. With a possibility to move down on demand, of course
I abstain from this point other than to say one model you can consider that other large (chemistry) software projects adopt is to have a largely alphabetical ranking, then have the first and/or last author(s) be those that are the brainchildren. Example, Example
