Consider a more explicit and simpler contributor acknowledgment workflow for project maintainers and contributors

[chrissimpkins]

My workflow for acknowledgment of user efforts currently includes a scan of included issue reports and pull requests with each new release, followed by an update of the project CONTRIBUTORS.md file. I attempt to link contributor GitHub accounts with their name on the CONTRIBUTORS.md page. This is a time consuming manual task for projects with a low-moderate number of contributors and I would venture to guess it is not a sustainable model for projects with large numbers of contributors who meet these criteria. My acknowledgment workflow includes far less information/modification of the contributors page than you propose here. I would consider modifying your spec to support the following:

1. encourage contributors to pull request their own information into the acknowledgment section/page that you specify
2. include an information page that explicitly defines the project specific contribution levels that meet criteria for inclusion as a contributor

This has been an issue for us in the Hack project where source code commits are a very minor component of the intellectual/design/development contributions that have occurred in the project and therefore acknowledgment of these efforts is an entirely manual process outside of the contributors list provided by GitHub. I've chosen to be very inclusive in the level of contribution necessary to be considered a project contributor because I highly value this input and it leads to modifications/improvements in the project. In my opinion, the acknowledgment is both appropriate and important for this project. If someone else were maintaining this project or a similar type of project, the criteria could be very different. IMO, a contributor is entitled to this information and I look forward to how you approach this issue as guidance for those of us who maintain open source projects.

As a project maintainer, I want to commit to the acknowledgement of, and actually acknowledge, contributions according to your specifications, but it needs to be feasible to do so when the proposal is a manual task like you suggest here. As a contributor to other projects, I want to understand the type of contribution that is necessary to be included as a project contributor and expect that contributions of my time at these levels are appropriately acknowledged. I think that you have the opportunity to try to bridge that divide here.

Kudos to you for this effort.

[kentcdodds]

Yeah, this definitely adds some overhead. You may be interested in what @jfmengels is working on here.

I definitely feel like having an external CONTRIBUTORS.md is acceptable for projects with a ton of contributors.

You may also be interested in what @mgechev is working on here. Though this only covers the people who have code/PR/issue contributions.

I agree with your first suggestion. As for the second suggestion, I would recommend that this definition lives in the specification. Projects can divert from the spec if they so choose, but they'll have to do that in their own contributing guidelines.

So I'll happily accept a PR that adds your first suggestion 👍

[chrissimpkins]

I would recommend that this definition lives in the specification

By this you mean that all who report an issue, submit a pull request, or contribute to the conversation in an issue report / pull request GitHub thread are included as project contributors?

[kentcdodds]

Yes, that's what I mean. Each of those scenarios you mentioned are valuable contributions to a project. But like I said:

Projects can divert from the spec if they so choose, but they'll have to do that in their own contributing guidelines.

[krmaxwell]

Just to throw in a 👍 for the spec supporting this in CONTRIBUTORS.md because, in large or even medium sized projects, this could get out of control. Additionally, some projects use their README.md for their primary documentation, which means it's already quite a lot of info for users to peruse.

None of that should take away from the fantastic effort to recognize and encourage all sorts of community contributions to a project, for sure!

[kentcdodds]

Yeah, I'm personally not convinced that using a CONTRIBUTORS.md file accomplishes nearly what putting it in the README.md does. So I'd say that you'd need a lot of contributors before you move it out. I'm willing to accept a PR that adds this disclaimer allowing maintainer prerogative on this subject, but I want the language to indicate that the preference is somewhere prominent for the project (whether that be a README or the website).

[Jameskmonger]

Sadly I don't think I've ever looked in a CONTRIBUTORS.md file, so I'm going to have to agree with @kentcdodds

[kentcdodds]

Yeah. It's gotta be somewhere where people can't help but see it for it to have the right effect of truly showing recognition and appreciation.

[chrissimpkins]

From #9 (comment)

Yes, that's what I mean.

We may differ in opinion here, but my feeling is that this is too inclusive of a definition as a project contributor and opens the automated approaches that you recommended to abuse. An all comers (rather than moderated all contributors) approach assumes that users use issue reports for project contributions alone. Many issue reports are clarifications, need for additional information style questions, & overlapping issue reports from those who did not take the time to search closed issues that have previously been addressed. I do not consider these contributions to a project. On the sometimes benign/sometimes nefarious side of things, well meaning issue reports can be pulled off topic and new issue reports can be submitted by a GitHub account user who has absolutely no constructive intent. I think that you will have a tough time with adoption if you cast this broad of a net with your term "all".

[kentcdodds]

I think you're misunderstanding what I'm saying. I'm not saying that anyone who files an issue gets on the list. I'm saying anyone who contributes to the project gets on the list. Contributions include anything listed in the specification. It says nothing about people who ask questions or file duplicates. But people who file bugs or answer questions certainly are contributing to the project.

the automated approaches that you recommended

I actually don't recommend @mgechev's approach because I believe that it could lead to this kind of abuse. But I called it out because I think it's cool work and think it's worth looking at. As for @jfmengels solution, it still requires human interaction to make it happen and I think that's a good thing.

Does that help clear up confusion?

[chrissimpkins]

@Jameskmonger & @kentcdodds

Sadly I don't think I've ever looked in a CONTRIBUTORS.md file, so I'm going to have to agree with @kentcdodds

Yeah. It's gotta be somewhere where people can't help but see it for it to have the right effect of truly showing recognition and appreciation.

I think that this effectively eliminates use in large projects distributed over a number of maintainers where I feel that this is likely most valuable and needed!

[kentcdodds]

Right... As I said:

So I'd say that you'd need a lot of contributors before you move it out. I'm willing to accept a PR that adds this disclaimer allowing maintainer prerogative on this subject, but I want the language to indicate that the preference is somewhere prominent for the project (whether that be a README or the website).

[chrissimpkins]

Does that help clear up confusion?

Yes it does. Thank you. I misunderstood your original response to the question and the automated link/image generators.

For point 1, this is actually an implementation issue and probably not an issue for your spec though I do see it as a problem. Automation won't be granular enough to define contributors, manual maintainer driven tasks will will be onerous for extremely active projects. Users should feel welcomed to add themselves to a contributors list where ever it may live in a repository and a mechanism is in place with the pull request.

I would be interested in your thoughts on point 2 though. Has your experience been that projects that include a CONTRIBUTING.md file commonly include information about how one will be acknowledged as a contributor to the project? My experience has been that these are largely instruction files that deal with how one contributes to the project, not how one's contributions will be acknowledged after that contribution. While point 1 was intended to make this spec easier to implement for the project maintainer, point 2 will without a doubt create additional work for this group of individuals. However, I think that this additional work creates a more responsible environment for the management and appropriate acknowledgment of open source contributions. The specification of the need for an explicit set of definitions for the term "contributor" would be very appropriate in a specification that is designed to acknowledge all contributors.

[kentcdodds]

Yes it does. Thank you.

Glad we got that worked out 👍

So I definitely recommend that all projects have a CONTRIBUTING.md file to define how to contribute, but I think that if a project wants to follow the spec, they can just direct people to this spec for them to know what contributions will result in them being added. As I said, projects can feel free to divert from the spec and they could specify that diversion in the CONTRIBUTING.md file.

As for managing additions to the list, I think that it primarily should be the responsibility of the contributor to add themselves. "It's our code. We're maintaining this project together." These are attitudes I hope that doing this will foster.

I think I may be missing something from what you're trying to say though :-)

[chrissimpkins]

I think I may be missing something from what you're trying to say though

Simply stated, the emoji list will not be explicit and project-specific enough to define the term contributor. It is good to have these general categories that include guidance about non-source code contributions. I think that this is an important first step to actually acknowledge that these are important contributions to a project irrespective of the way in which GitHub classifies a contributor. I am suggesting that you also provide guidance within the spec that projects offer a project-specific set of definitions about how contributors achieve the contribution milestones in your contribution category list (currently called emoji key) and if project maintainers elect not to support some of the categories in the spec as defined over the course of time by yourselves and others who weigh in here, that this information is explicit as well. I think that we can do a much better job with objectivity and transparency in the relationship between maintainers and contributors and a spec like this is a great place to start.