mirror of
https://github.com/all-contributors/cli.git
synced 2025-01-09 21:46:29 +00:00
docs: centralize docs on website (#153)
* docs: centralize docs on website * Update README.md * Update README.md
This commit is contained in:
Jake Bolam
GitHub
parent
12df8685c2
commit
65eea1b82f
1 changed files with 2 additions and 189 deletions
191
README.md
191
README.md
|
|
@ -32,195 +32,9 @@ This is a tool to help automate adding contributor acknowledgements according to
|
||||||
the [all-contributors](https://github.com/all-contributors/all-contributors)
|
the [all-contributors](https://github.com/all-contributors/all-contributors)
|
||||||
specification for your GitHub or GitLab repository.
|
specification for your GitHub or GitLab repository.
|
||||||
|
|
||||||
## Table of Contents
|
## Using the all-contributors-cli
|
||||||
|
|
||||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
If you're looking to use the cli, head over to [the cli docs on all-contributors.js.org](https://all-contributors.js.org/docs/cli/overview). The all-contributors website contains all the information required to install, configure and use the all-contributors-cli.
|
||||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
|
||||||
|
|
||||||
- [Installation](#installation)
|
|
||||||
- [Usage](#usage)
|
|
||||||
- [Generating the contributors list](#generating-the-contributors-list)
|
|
||||||
- [Add/update contributors](#addupdate-contributors)
|
|
||||||
- [Check for missing contributors](#check-for-missing-contributors)
|
|
||||||
- [Configuration](#configuration)
|
|
||||||
- [Contributors](#contributors)
|
|
||||||
- [LICENSE](#license)
|
|
||||||
|
|
||||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
|
||||||
|
|
||||||
## 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:
|
|
||||||
|
|
||||||
```console
|
|
||||||
# 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`:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"scripts": {
|
|
||||||
"contributors:add": "all-contributors add",
|
|
||||||
"contributors:generate": "all-contributors generate"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
and use them via `npm run`:
|
|
||||||
|
|
||||||
```console
|
|
||||||
npm run contributors:add -- jfmengels doc
|
|
||||||
npm run contributors:generate
|
|
||||||
```
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
A 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 :smiley_cat:
|
|
||||||
|
|
||||||
### Generating the contributors list
|
|
||||||
|
|
||||||
Please add following placeholders in [`files`](#configuration) to specify the generation area first.
|
|
||||||
|
|
||||||
<pre>
|
|
||||||
<!-- ALL-CONTRIBUTORS-<!-- hack break -->LIST:START - Do not remove or modify this section -->
|
|
||||||
<!-- ALL-CONTRIBUTORS-<!-- hack break -->LIST:END -->
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
Then use `generate` to generate the contributors list and inject it into your
|
|
||||||
contributors file. Contributors will be read from your configuration file.
|
|
||||||
|
|
||||||
```console
|
|
||||||
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.
|
|
||||||
|
|
||||||
```console
|
|
||||||
# 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
|
|
||||||
([see the specs](https://github.com/all-contributors/all-contributors#emoji-key)):
|
|
||||||
|
|
||||||
- blog: [📝](# 'Blogposts')
|
|
||||||
- bug: [🐛](# 'Bug reports')
|
|
||||||
- code: [💻](# 'Code')
|
|
||||||
- design: [🎨](# 'Design')
|
|
||||||
- doc: [📖](# 'Documentation')
|
|
||||||
- eventOrganizing: [📋](# 'Event Organizing')
|
|
||||||
- example: [💡](# 'Examples')
|
|
||||||
- financial: [💵](# 'Financial')
|
|
||||||
- fundingFinding: [🔍](# 'Funding Finding')
|
|
||||||
- ideas: [🤔](# 'Ideas, Planning, & Feedback')
|
|
||||||
- infra: [🚇](# 'Infrastructure (Hosting, Build-Tools, etc)')
|
|
||||||
- maintenance [🚧](# 'Maintenance')
|
|
||||||
- platform: [📦](# 'Packaging/porting to new platform')
|
|
||||||
- plugin: [🔌](# 'Plugin/utility libraries')
|
|
||||||
- question: [💬](# 'Answering Questions')
|
|
||||||
- review: [👀](# 'Reviewed Pull Requests')
|
|
||||||
- security: [🛡](# 'Security')
|
|
||||||
- talk: [📢](# 'Talks')
|
|
||||||
- test: [⚠️](# 'Tests')
|
|
||||||
- tool: [🔧](# 'Tools')
|
|
||||||
- translation: [🌍](# 'Translation')
|
|
||||||
- tutorial: [✅](# 'Tutorials')
|
|
||||||
- userTesting: [📓](# 'User Testing')
|
|
||||||
- video: [📹](# 'Videos')
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
```console
|
|
||||||
# set private token on linux
|
|
||||||
export PRIVATE_TOKEN=your_private_token
|
|
||||||
# set private token on windows
|
|
||||||
set PRIVATE_TOKEN=your_private_token
|
|
||||||
```
|
|
||||||
|
|
||||||
### 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.
|
|
||||||
|
|
||||||
```console
|
|
||||||
all-contributors check
|
|
||||||
```
|
|
||||||
|
|
||||||
> Due to GitHub API restrictions, this command only works for projects with less
|
|
||||||
> than 500 contributors. (Unless you set a PRIVATE_TOKEN) as mentioned below
|
|
||||||
|
|
||||||
## 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:
|
|
||||||
|
|
||||||
| 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. |
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"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](https://developer.github.com/v3/rate_limit/).
|
|
||||||
|
|
||||||
> Private token is your personal access token to authenticate with the GitHub API.
|
|
||||||
|
|
||||||
## Contributors
|
## Contributors
|
||||||
|
|
||||||
|
|
@ -241,7 +55,6 @@ Thanks goes to these wonderful people
|
||||||
This project follows the
|
This project follows the
|
||||||
[all-contributors](https://github.com/all-contributors/all-contributors)
|
[all-contributors](https://github.com/all-contributors/all-contributors)
|
||||||
specification. Contributions of any kind are welcome!
|
specification. Contributions of any kind are welcome!
|
||||||
We are also [looking for maintainers](https://github.com/all-contributors/all-contributors-cli/issues/129)
|
|
||||||
|
|
||||||
## LICENSE
|
## LICENSE
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue