diff --git a/.all-contributorsrc b/.all-contributorsrc index 8f53d4f7..12985b20 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -5,6 +5,11 @@ "README.md" ], "imageSize": 100, + "customContributions": { + "mentoring": "👨‍🏫", + "funding": "💵", + "translation": "🌍" + }, "contributors": [ { "login": "kentcdodds", @@ -958,6 +963,15 @@ "contributions": [ "bug" ] + }, + { + "login": "test-user", + "name": "test-user", + "avatar_url": "https://avatars.githubusercontent.com/u/2154595?v=4", + "profile": "https://github.com/test-user", + "contributions": [ + "mentoring" + ] } ], "repoType": "github", diff --git a/docs/bot/configuration.md b/docs/bot/configuration.md index 13b61428..f8515cc8 100644 --- a/docs/bot/configuration.md +++ b/docs/bot/configuration.md @@ -24,6 +24,7 @@ These are the keys you can specify: | `commitConvention` | Commit convention ([`angular`](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines), [`atom`](https://github.com/atom/atom/blob/master/CONTRIBUTING.md#git-commit-messages), [`ember`](https://guides.emberjs.com/v1.10.0/contributing/#toc_commits), [`eslint`](https://eslint.org/docs/1.0.0/developer-guide/contributing#step-2-make-your-changes), [`jshint`](https://jshint.com/contribute/), [`gitmoji`](https://gitmoji.carloscuesta.me/), or `none`). | Default: `angular` | | `contributorsPerLine` | Maximum number of columns for the contributors table. | Default: `7` | | `contributorsSortAlphabetically` | `true`: Sort alphabetically. `false`: Display in order of addition. | Default: `false` | +| `customContributions` | Define custom contribution types with their associated emojis. | Example: `{"mentoring": "👨‍🏫", "funding": "💵"}` | | `badgeTemplate` | Define your own lodash template to generate the badge. | | | `contributorTemplate` | Define your own lodash template to generate the contributor. | | | `wrapperTemplate` | Define your own lodash template to wrap the list of contributors | | @@ -43,6 +44,11 @@ These are the keys you can specify: "commit": false, "contributorsPerLine": 7, "contributorsSortAlphabetically": false, + "customContributions": { + "mentoring": "👨‍🏫", + "funding": "💵", + "translation": "🌍" + }, "badgeTemplate": "[![All Contributors](https://img.shields.io/github/all-contributors/<%= projectOwner %>/<%= projectName %>?color=ee8449&style=flat-square)](#contributors)", "contributorTemplate": "\">\" width=\"<%= options.imageSize %>px;\" alt=\"\"/>
<%= contributor.name %>", "wrapperTemplate": "\n\n <%= bodyContent %> \n<%= tableFooterContent %>
\n\n", @@ -57,27 +63,4 @@ These are the keys you can specify: "skipCi": true, "contributors": [] } -``` - -#### Moving the All Contributors table into a different file - -As you know, the default file for the contributors table is `README.md`. But if your project has tons of contributors, it doesn't make sense to include the All Contributors table in the `README.md` file. Instead, you can use a different file to do so. - -Here are the steps that may help you in achieving that. For the sake of this tutorial, the different file that we'll use is going to be named `CONTRIBUTORS.md`. - -1. Install the bot. See the [Installation](installation) page for instructions. -2. Add your first contributor. See the [Bot Usage](usage) page for instructions. -3. Create the `CONTRIBUTORS.md` file. -4. Copy the code which can be found in [this guide](installation#3-create-a-readmemd). -5. Modify the `files` key in the `.all-contributorsrc` JSON file to match your new file name. - - ```json - { - "files": [ - "CONTRIBUTORS.md" - ], - ... - } - ``` - -6. Now you should be good to go. New contributors will be added to this new file instead of the `README.md` file. +``` \ No newline at end of file diff --git a/docs/bot/usage.md b/docs/bot/usage.md index e9fb8514..a9a3060d 100644 --- a/docs/bot/usage.md +++ b/docs/bot/usage.md @@ -33,7 +33,22 @@ please add @ for . please add @ for . ``` -**\**: See the [Emoji Key (Contribution Types Reference)](../emoji-key) for a list of valid `contribution` types. +**\**: See the [Emoji Key (Contribution Types Reference)](../emoji-key) for a list of valid `contribution` types. You can also use custom contribution types defined in your `.all-contributorsrc` file's `customContributions` field. + +For example, if you have defined custom contributions in your `.all-contributorsrc`: +```json +{ + "customContributions": { + "mentoring": "👨‍🏫", + "funding": "💵" + } +} +``` + +You can use them like this: +```plaintext +@all-contributors please add @username for mentoring,funding +``` The bot will then create a Pull Request to add the contributor, then reply with the pull request details. diff --git a/docs/cli/usage.md b/docs/cli/usage.md index e7de2b3a..1764aa60 100644 --- a/docs/cli/usage.md +++ b/docs/cli/usage.md @@ -34,6 +34,8 @@ Where `username` is the user's GitHub or Gitlab username, and `contribution` is `,`-separated list of contributions. See the [Emoji Key (Contribution Types Reference)](../emoji-key) for a list of valid `contribution` types. +> **Note:** While the CLI supports custom contribution types defined in your `.all-contributorsrc` file, there is currently a limitation where you can only add one custom contribution type at a time. For multiple custom contributions, you'll need to add them one at a time or use the bot instead. + > **GitLab Users**: See the [additional requirements for GitLab users](#gitlab-users) ### `all-contributors check` diff --git a/docs/emoji-key.md b/docs/emoji-key.md index bde19bd4..38b95ab6 100644 --- a/docs/emoji-key.md +++ b/docs/emoji-key.md @@ -8,6 +8,8 @@ sidebar_label: Emoji Key ✨ > To have a contribution added when using the [Bot](bot/overview) or [CLI](cli/overview) use the keyword in the `Type` column. The bot will also use [basic Natural Language Parsing](https://github.com/all-contributors/app/blob/master/lib/parse-comment.js) to determine your contribution intent. +> **Note:** In addition to these standard contribution types, you can define custom contribution types in your project's `.all-contributorsrc` file using the `customContributions` field. See the [Bot Configuration](bot/configuration#custom-contribution-types) for more details. + Emoji/Type | Represents | Comments :---: | :---: | :---: 🔊
`audio` | Audio | Podcasts, background music or sound effects diff --git a/docs/specification.md b/docs/specification.md index 3411595f..ca214e2c 100644 --- a/docs/specification.md +++ b/docs/specification.md @@ -19,11 +19,13 @@ Open source projects should include the following mandatory items to support the 2. 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. - - An 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](emoji-key). + - An indication of the Contribution Category in text or icon image format using either: + - The defined Contribution Categories and their emoji images (see [Emoji Key](emoji-key)) + - Custom contribution types defined in your project's `.all-contributorsrc` file + - A link to the Contribution Category in text or emoji format - The list of contributors can be spread across multiple lines (each technically being its 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 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 the exclusion of an individual from the Contributor list based upon the 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. +3. Projects should define contributors as those who contribute to a project in any of the standard or custom 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 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 the exclusion of an individual from the Contributor list based upon the 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. > **Pro tip:** You can use [the @all-contributors bot 🤖](bot/overview) to automate acknowledging contributors to your open source projects ✨