Add authorship policy for paper and software archives #13
Conversation
|
Hi @santisoler thanks for starting this! I'll have a look as soon as possible. |
|
@santisoler I updated the text based on our discussion last week. What do you think? |
There was a problem hiding this comment.
I really like the way it looks! I like that now it's an invitation to contribute.
I think I would change the part where we define who's going to be listed as author on a new Zenodo release. Using git shortlog vX.0.0...HEAD -sne is kind of problematic if vX.0.0 is the last major release.
For example, if we are about to release v3.0.0 we would run git shortlog v2.0.0...HEAD -sne and anyone that made a contribution since v2.0.0 will appear.
But as soon we release v3.1.0, we would run git shortlog v3.0.0...HEAD -sne (because v3.0.0 is the last major release) and only the ones that made contributions since v3.0.0 will appear.
I think that's not fair and we should include all contributors from the previous major release (there's a word in Spanish for saying the one before the last, but don't know how to translate it).
What do you think?
|
That's a good point. What I meant was that the order will be defined like that, but everyone who ever contributed will be invited as author. What would you think of that? |
|
@fatiando/contributors @fatiando/pooch I'd be interested to know your thoughts on this. We're drafting a document outlining the criteria for authorship in archives and publications and how we go about giving credit to contributors. This document will be become a part of every repo we have so it would be great to get everyone's opinion. |
Co-Authored-By: Hugo van Kemenade <[email protected]>
|
I talked this over with @santisoler and we made a few small changes to the author order:
Note that all of these are subject to change based on common sense and consensus. |
leouieda
changed the title
|
Thanks for the fixes @hugovk! |
AUTHORSHIP.md
Outdated
| The order of authors will be defined by the number of commits made since the | ||
| previous major release that has an associated paper (`git shortlog vX.0.0...HEAD -sne`). | ||
| The order of any author who hasn't made any commits will be decided by all authors. | ||
| The order can also be changed on a case-by-case basis. |
There was a problem hiding this comment.
I think this looks great. Ordering authorship by the number of commits makes sense, and gives positive feedback to those who put in the most work on each release.
AUTHORSHIP.md
Outdated
|
|
||
| ## Authorship on Zenodo archives of releases | ||
|
|
||
| Anyone who has contributed to the repository (i.e., is know to `git log`) will |
There was a problem hiding this comment.
Should (i.e., is know to 'git log') be known to 'git log' or even documented by 'git log'?
There was a problem hiding this comment.
Thanks for the suggestion @jessepisel. I changed to "appears on git log"
| > **Note**: These policies are not set in stone and may be changed to | ||
| > accommodate the growth of the project or the preferences of the community. | ||
|
|
||
| ## The `AUTHORS.md` file |
There was a problem hiding this comment.
I 100% agree that in order for contributors to be included they need to add themselves to AUTHORS.md. If I remember correctly, this is on the checklist for pull requests?
There was a problem hiding this comment.
Thanks for the feedback @jessepisel!
It's not exactly on the pull requests checklist, but your memory is on a good track: after the first PR of a new contributor is merged, a bot instruct them to open a new PR to add themselves to AUTHORS.md.
I've seen that most people ignore or forget to do it. So this is one of the things we want to change: we will ask them to add their full names (with optional affiliation and ORCID) to AUTHORS.md from within the PR before it's merged. This would help the new contributors because they won't need to open a second PR (what could be challenge if you are new on GitHub) and help to remind the maintainers to explicitly ask the new contributors to add themselves.
There was a problem hiding this comment.
Sounds like a useful addition for the checklist in the PR template. Might be useful to create an org-wide default for this (and possibly other community files), see:
There was a problem hiding this comment.
Thanks @hugovk! In fact we were thinking of adding the PR template here (to fatiando/contributing) where all the community files that should be shared by every Fatiando package live.
Might be useful to create an org-wide default for this (and possibly other community files), see:
https://help.github.com/en/github/building-a-strong-community/creating-a-default-community-health-file
Thanks for the info. I wasn't aware of the default community files repository. It seems a very nice option. Although I'm curious if community files are somehow automatically updated if any change is made on the .github repository.
FYI, the fatiando/contributing repo satisfy the same needs as the .github repo. While any new Fatiando repository must be created through the fatiando/package-template, a cookiecutter template.
The nice thing about fatiando/contributing is that whenever we push any new commit to its master, @fatiando-bot automatically opens a PR on every Fatiando library asking to incorporate the changes on the community files.
Maybe we could think of renaming this repo to .github and keep @fatiando-bot doing its job.
By the way, @leouieda, I'm curious about how the community files are generated when creating a new repository from fatiando/package-template. Are they hardcoded or are they fetched from fatiando/contributing?
There was a problem hiding this comment.
That sounds quite nifty that @fatiando-bot will do that syncing!
Yes, you wouldn't need to do any syncing when things are in .github, it should just read it straight from there (unless a repo has its own version of the file).
There was a problem hiding this comment.
I've just experienced a little with the .github repository.
So the community files are just linked on any library that belongs to the project. For example, when opening a new Issue, a link to the Contributor Guidelines appears. But the community files are not automatically included on them.
I think we may want to avoid that and explicitly include the community files on each repo.
What do you think?
There was a problem hiding this comment.
I've only used it for ISSUE_TEMPLATE.md and PULL_REQUEST_TEMPLATE.md, where it pre-fills the new issue or PR edit box. For example, in a repo which doesn't have its own ISSUE_TEMPLATE.md, it pre-fills this one from the .github repo:
For the guidelines and code of conduct, if I click to create a new issue in a repo here, I see:
They link to:
- https://github.com/fatiando/harmonica/blob/master/CONTRIBUTING.md
- https://github.com/fatiando/harmonica/blob/master/CODE_OF_CONDUCT.md
Is that acceptable if they linked here?
There was a problem hiding this comment.
I see!
My thoughts are:
- All community files (
CODE_OF_CONDUCT.md,CONTRIBUTING.md,MAINTENANCE.md, etc) should live inside each repository. I'm thinking it's better this way because releases uploaded to archives will have the full documentation of the repository. Besides, I think JOSS requires to have this on the repository, am I right? - Maybe we could store PR and ISSUES templates on a new
fatiando/.githubrepo. So we don't have to bother to update the ones that live inside the repositories if we make changes. Besides, there's no point of archiving these files, they are useful only within GitHub.
Sorry for changing my mind on every comment, I'm just sharing thoughts and ideas to see if they are accurate or if there are better options.
There was a problem hiding this comment.
I don't know if it's a JOSS requirement, but yes, that sounds like a good approach!
There was a problem hiding this comment.
@hugovk I didn't know about the .github repo either. Nice!
I agree with @santisoler about leaving the community files where they are (it is a JOSS requirement) and creating a new .github repo to host the templates. It would be fine if they link to the files in this repo (contributing) instead of the ones on the individual repos.
Talking to @djhoese on twitter, he pointed out that they can get a lot of people to add themselves to their authors file without much prodding. I'd be in favour of adding it to the checklist instead of having it as a message from the bot (which nobody seems to read).
|
Alright, I have added links to the authorship file in the maintenance and contributing guides. I also created the fatiando/.github repo and added our current templates to it. fatiando/.github#2 will add "include yourself in AUTHORS.md" to the PR checklist and modify the welcome message from the bot as well (I'd appreciate some reviews on that). This seems good to go so I'll hit the merge button! 🎉 Thank you for the input everyone! |
The authorship guidelines introduced in fatiando/community#13 specify that authors on Zenodo archives will be taken from the AUTHORS.md file and need to have full names, affiliation, and ORCIDs (optionally) included in that file.
The authorship guidelines introduced in fatiando/community#13 specify that authors on Zenodo archives will be taken from the AUTHORS.md file and need to have full names, affiliation, and ORCIDs (optionally) included in that file.
The authorship guidelines introduced in fatiando/community#13 specify that authors on Zenodo archives will be taken from the AUTHORS.md file and need to have full names, affiliation, and ORCIDs (optionally) included in that file.
The authorship guidelines introduced in fatiando/community#13 specify that authors on Zenodo archives will be taken from the AUTHORS.md file and need to have full names, affiliation, and ORCIDs (optionally) included in that file.
The authorship guidelines introduced in fatiando/community#13 specify that authors on Zenodo archives will be taken from the AUTHORS.md file and need to have full names, affiliation, and ORCIDs (optionally) included in that file. Update the file with everyone who has contributed so far.
Add a section to the welcome message for new contributors and a checklist item for adding their name to the authors file. As discussed in fatiando/community#13
As instructed by the new authorship guidelines (fatiando/community#13) contributors who wish to be included in Zenodo archives need to be listed in `AUTHORS.md` and include affiliation and ORCID. Include current contributors in the file so it matches what we will put in Zenodo.
The authorship guidelines introduced in fatiando/community#13 specify that authors on Zenodo archives will be taken from the AUTHORS.md file and need to have full names, affiliation, and ORCIDs (optionally) included in that file.
Add
AUTHORSHIP.mdfile containing authorship policies for any library belonging to Fatiando a Terra.This document lays out the general rules for giving credit to contributors. Our main goal is to be clear about this upfront and provide an incentive for academics looking to get involved in the project.