Skip to content
This repository has been archived by the owner on Jan 29, 2023. It is now read-only.

Acknowledgement Guidelines

Jump to bottom
Andrew Redican edited this page Jul 31, 2018 · 2 revisions

These are the guidelines thought by all-contributors for recognizing contributors to this open source project in a way that rewards each and every contribution, not just code. We would like to make this practice our own.

The basic idea is this:

Use the project README (or other prominent public documentation page in the project) to recognize the contributions of members of the project community.

People are giving of themselves and their free time to contribute to open source projects in so many ways. It can be a real time sink sometimes and so they should be praised for all their contributions (code or not).

Specification

Mandatory

Open source projects should include the following mandatory items in order to support the All Contributors specification:

A "Contributors" section in a prominent site of the project repository documentation that includes a list of all project contributors

  • The goal should be to use the most prominent site of the project documentation when feasible. In many cases, this is the project README file
  • Consider use of a CONTRIBUTORS file in the top level of the repository when the number of project contributors exceeds a level at which it is feasible to use the README file to acknowledge contributions. In this case, a prominent link to the CONTRIBUTORS file should be included on the README page under the "Contributors" heading

The listings should be formatted as a table with the following information about the project contributors:

  • Name
  • URL link to a site where more information can be learned about the contributor. This URL may be determined by the contributor at the project's discretion.
  • Indication of the Contribution Category in text or icon image format using the defined Contribution Categories and/or Contribution Categories emoji images (see below).
  • A link to the Contribution Category in text or emoji format using the defined Contribution Categories and/or Contribution Categories emoji.
  • The list of contributors can be spread across multiple lines (each technically being its own table) as needed.
  • The order of contributors is immaterial to the spec. Order them how you wish.

3. Projects should define contributors as those who contribute to a project in any of the Contribution Categories at any level of contribution.

  • This specification is, by definition, inclusive of all contributions. In cases where projects deviate from the Contribution Categories or require a specific contribution level in order to meet criteria as a project contributor, the project should provide explicit documentation of the definitions that satisfy the project contributor criteria in the CONTRIBUTING document or a similar prominent public document at the top level of the project repository. This specification recommends against exclusion of an individual from the Contributor list based upon perceived level of contribution. Instead, projects should use indicators of effort within a list that remains inclusive of all contributors to the project at any level of effort. If used, these effort indicators are at the discretion of the project and are not currently specified.

Optional

Projects should consider the following optional items as part of their commitment to the All Contributors specification:

  1. The user's avatar can be included and is recommended.
  2. An optional link from the Contribution Category indicator to the category-specific contribution(s) can be included to provide additional information about the project contribution(s) as detailed in the section below.

CLI

This project uses all-contributors-cli to automate maintenance of the contributors' list. See full documentation.

Installation

This module is distributed via [npm][npm] which is bundled with [node][node] and should be installed as one of your project's devDependencies:

npm install --save-dev all-contributors-cli

Then init the project using init and answer a few questions:

# Use npx for npm@^5.2.0
npx all-contributors init
# Or directly execute the bin
./node_modules/.bin/all-contributors init

Then you can add these scripts to your package.json:

{
  "scripts": {
    "contributors:add": "all-contributors add",
    "contributors:generate": "all-contributors generate"
  }
}

and use them via npm run:

npm run contributors:add -- jfmengels doc
npm run contributors:generate

Usage

Generating the contributors list

Please add following placeholders in files to specify the generation area first.

<!-- ALL-CONTRIBUTORS-LIST: START - Do not remove or modify this section -->
<!-- ALL-CONTRIBUTORS-LIST:END -->

Then use generate to generate the contributors list and inject it into your contributors file. Contributors will be read from your configuration file.

all-contributors generate

Add/update contributors

Use add to add new contributors to your project, or add new ways in which they have contributed. They will be added to your configuration file, and the contributors file will be updated just as if you used the generate command.

# Add new contributor <username>, who made a contribution of type <contribution>
all-contributors add <username> <contribution>
# Example:
all-contributors add jfmengels code,doc

Where username is the user's GitHub or Gitlab username, and contribution is a ,-separated list of ways to contribute, from the following list:

Check for missing contributors

Use check to compare contributors from GitHub with the ones credited in your .all-contributorsrc file, in order to make sure that credit is given where it's due.

all-contributors check

Due to GitHub API restrictions, this command only works for projects with less than 500 contributors.

Configuration

You can configure the project by updating the .all-contributorsrc JSON file. The data used to generate the contributors list will be stored in there, and you can configure how you want all-contributors-cli to generate the list.

These are the keys you can specify:

  • files: Array of files to update. Default: ['README.md']
  • projectOwner: Name of the user the project is hosted by. Example: jfmengels/all-contributors-cli --> jfmengels. Mandatory.
  • projectName: Name of the project. Example: jfmengels/all-contributors-cli --> all-contributors-cli. Mandatory.
  • repoType: Type of repository. Must be either github or gitlab. Default: github.
  • repoHost: Points to the repository hostname. Change it if you use a self hosted repository. Default: https://github.com if repoType is github, and https://gitlab.com if repoType is gitlab.
  • types: Specify custom symbols or link templates for contribution types. Can override the documented types.
  • imageSize: Size (in px) of the user's avatar. Default: 100.
  • contributorsPerLine: Maximum number of columns for the contributors table. Default: 7.
  • contributorTemplate: Define your own template to generate the contributor list.
  • badgeTemplate: Define your own template to generate the badge.

Emoji keys

Emoji CLI Code Represents Links to Comment
💬 question Answering Questions (in Issues, Stack Overflow, Gitter, Slack, etc.)
🐛 bug Bug reports https://github.com/${ownerName}/${repoName}/issues?q=author%3A${username}
📝 blog Blogposts the blogpost
💻 code Code https://github.com/${ownerName}/${repoName}/commits?author=${username}
📖 doc Documentation https://github.com/${ownerName}/${repoName}/commits?author=${username}, Wiki, or other source of documentation
🎨 design Design the logo/iconography/visual design/etc.
💡 example Examples the examples
📋 eventOrganizing Event Organizers event page
💵 financial Financial Support relevant page people or orgs who provide financial support
🔍 fundingFinding Funding/Grant Finders people who help find financial support
🤔 ideas Ideas & Planning
🚇 infra Infrastructure (Hosting, Build-Tools, etc) link to source file (like travis.yml) in repo, if applicable
📦 platform Packaging/porting to support a new platform
🔌 plugin Plugin/utility libraries the repo home
👀 review Reviewed Pull Requests
🔧 tool Tools the repo home
🌍 translation Translation the translated content
⚠️ test Tests https://github.com/${ownerName}/${repoName}/commits?author=${username}
✅ tutorial Tutorials the tutorial
📢 talk Talks the slides/recording/repo/etc.
📹 video Videos the video

Notes for repository maintainers

Contributors should be recognised as soon as the contribution is discovered to help ensure their efforts are not overlooked when the list gets updated at a later date. This can be difficult for contributions that are not the result of a commit to repository but do your best to minimise the time between the contribution and updating the list.

Being the owner or a maintainer of the repository does not mean you are solely responsible for keeping the list of contributors up to date. You should encourage contributors to add themselves to the list as much as possible. This can be in the form of a comment on the issue, blog or answer, or through more direct forms of communication where appropriate.

Many contributors may not realise that their efforts are sufficient for recognition in the contributors list. This might be because they have not read or understood the definition of a contributor as set out in this specification, or because they do not feel like it is significant enough. In these cases, you should still encourage them to add themselves, but it may be necessary for you to add the contributor yourself (though it's a good idea to do so in the form of a pull request to make sure they're ok with being added).

In the end, there are no hard and fast rules for when a contribution has to be added to the list, just do your best to be fair and to ensure all contributors are recognised.

Clone this wiki locally