There is now a GitHub Bot for automating the maintenance of your contributors table ✨
Say goodbye to command line tool dependencies and hello to the @all-contributors bot 🤖
Automate acknowledging contributors to your open source projects
You want to implement the All Contributors spec, but don't want to maintain the table by hand
This is a tool to help automate adding contributor acknowledgements according to the all-contributors specification for your GitHub or GitLab repository.
This module is distributed via npm which is bundled with 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 initThen 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:generateA quick note: We recommend that you install all-contributors-cli as a dependency in your project.
If you do that then you can run the all-contributors binary from within your package.json scripts, or you can run it in your terminal with npx all-contributors.
Below we'll just show all-contributors to keep things simple, but if you're having any difficulties, then give the npx all-contributors-cli route a try 😺
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 generateUse 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,docWhere username is the user's GitHub or Gitlab username, and contribution is a
,-separated list of ways to contribute, from the following list
(see the specs):
- blog: 📝
- bug: 🐛
- code: 💻
- design: 🎨
- doc: 📖
- eventOrganizing: 📋
- example: 💡
- financial: 💵
- fundingFinding: 🔍
- ideas: 🤔
- infra: 🚇
- platform: 📦
- plugin: 🔌
- question: 💬
- review: 👀
- security: 🛡
- talk: 📢
- test:
⚠️ - tool: 🔧
- translation: 🌍
- tutorial: ✅
- userTesting: 📓
- video: 📹
Please note that if you are using a self-hosted gitlab instance, before adding
contributor, you need to set an environment variable named PRIVATE_TOKEN first.
Private token is the personal access token to authenticate with the GitLab API.
# set private token on linux
export PRIVATE_TOKEN=your_private_token
# set private token on windows
set PRIVATE_TOKEN=your_private_tokenUse 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 checkDue to GitHub API restrictions, this command only works for projects with less than 500 contributors. (Unless you set a PRIVATE_TOKEN) as mentioned below
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:
| Option | Description | Example/Default |
|---|---|---|
projectName |
Mandatory, name of the project. | Example: all-contributors-cli |
projectOwner |
Mandatory, name of the user the project is hosted by. | Example: jfmengels |
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 |
files |
Array of files to update. | Default: ['README.md'] |
imageSize |
Size (in px) of the user's avatar. | Default: 100 |
commit |
Auto-commit badge when adding contributors. | true or false |
contributorsPerLine |
Maximum number of columns for the contributors table. | Default: 7 |
badgeTemplate |
Define your own lodash template to generate the badge. | |
contributorTemplate |
Define your own lodash template to generate the contributor. | |
types |
Specify custom symbols or link templates for contribution types. Can override the documented types. |
{
"projectName": "all-contributors-cli",
"projectOwner": "jfmengels",
"repoType": "github",
"repoHost": "https://github.com",
"files": ["README.md"],
"imageSize": 100,
"commit": false,
"contributorsPerLine": 7,
"badgeTemplate": "[](#contributors)",
"contributorTemplate": "<%= avatarBlock %><br /><%= contributions %>",
"types": {
"custom": {
"symbol": "🔭",
"description": "A custom contribution type.",
"link": "[<%= symbol %>](<%= url %> \"<%= description %>\"),"
}
},
"contributors": []
}In some cases you may see the error message 'GitHub API rate limit exceeded for xxx'. You may need to set an environment variable named PRIVATE_TOKEN in order to circumvent this GitHub rate limit.
Private token is your personal access token to authenticate with the GitHub API.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind are welcome! We are also looking for maintainers
MIT