mirror of
https://github.com/all-contributors/cli.git
synced 2025-01-09 13:36: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)
|
||||
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 -->
|
||||
<!-- 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.
|
||||
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.
|
||||
|
||||
## Contributors
|
||||
|
||||
|
|
@ -241,7 +55,6 @@ Thanks goes to these wonderful people
|
|||
This project follows the
|
||||
[all-contributors](https://github.com/all-contributors/all-contributors)
|
||||
specification. Contributions of any kind are welcome!
|
||||
We are also [looking for maintainers](https://github.com/all-contributors/all-contributors-cli/issues/129)
|
||||
|
||||
## LICENSE
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue