Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mntnr/name-your-contributors

Name your GitHub contributors; get commits, issues, and comments
https://github.com/mntnr/name-your-contributors

community contribute contributing contributors github nodejs

Last synced: about 1 month ago
JSON representation

Name your GitHub contributors; get commits, issues, and comments

Awesome Lists containing this project

README

        

# name-your-contributors

[![npm version](https://badge.fury.io/js/name-your-contributors.svg)](https://badge.fury.io/js/name-your-contributors)
[![Build and Deploy](https://github.com/mntnr/name-your-contributors/actions/workflows/nodejs.yml/badge.svg)](https://github.com/mntnr/name-your-contributors/actions/workflows/nodejs.yml)
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)

> Name your GitHub contributors; get commits, issues, and comments

`name-your-contributors` gets all of the code reviewers, commenters, issue and PR creators from your organization or repo.

## Table of Contents

- [Background](#background)
- [Contributors](#contributors)
- [Install](#install)
- [API Limits and setting up a GitHub Token](#api-limits-and-setting-up-a-github-token)
- [Caveats](#caveats)
- [Usage](#usage)
- [From Code](#from-code)
- [From the Command Line](#from-the-command-line)
- [Config File](#config-file)
- [Result formats](#result-formats)
- [Default](#default)
- [CSV](#csv)
- [Full Contribution Tree](#full-contribution-tree)
- [Condensed](#condensed)
- [API](#api)
- [orgContributors({orgName, token, before, after})](#orgcontributorsorgname-token-before-after)
- [token](#token)
- [org](#org)
- [opts.after](#optsafter)
- [opts.before](#optsbefore)
- [repoContributors({user, repo, token, before, after})](#repocontributorsuser-repo-token-before-after)
- [opts.user](#optsuser)
- [opts.repo](#optsrepo)
- [Development](#development)
- [Contribute](#contribute)
- [License](#license)

## Background

NYC started as a means of showing who has been active in a repository or an org over a certain period of time. Originally it was used to populate people for the [IPFS](https://github.com/ipfs/ipfs) newsletter - every week, I would run it again to show new contributions. GitHub doesn't count a lot of contributions as contributions, instead looking at commits alone. NYC looks at _all_ of your community, and logs who did what.

It spits out to a JSON object, because that's the most portable system for using it elsewhere with the formatting you need. It also uses GraphQL to cut down on the amount of queries, as it is pretty intensive otherwise.

### Contributors

These people have helped make Name Your Contributors:

- [@Berkmann18](https://github.com/Berkmann18)
- [@RichardLitt](https://github.com/RichardLitt)
- [@daviddias](https://github.com/daviddias)
- [@dignifiedquire](https://github.com/dignifiedquire)
- [@gr2m](https://github.com/gr2m)
- [@greenkeeper](https://github.com/greenkeeper)
- [@jbenet](https://github.com/jbenet)
- [@jozefizso](https://github.com/jozefizso)
- [@jywarren](https://github.com/jywarren)
- [@kentcdodds](https://github.com/kentcdodds)
- [@tgetgood](https://github.com/tgetgood)
- [@waldyrious](https://github.com/waldyrious)

Using the [`jq`](https://github.com/stedolan/jq) JSON parsing library (you can use your own), this list was autogenerated like this:

```sh
node src/cli.js -u mntnr -r name-your-contributors | jq '[ .[][].login | " - [@ \(.)](https://github.com/\(.))"]' | jq unique | jq -r .[]
```

Which is a whole lot more useful than manually looking for contributors!

## Install

```sh
$ npm install --save name-your-contributors
```

### API Limits and setting up a GitHub Token

You also need to get a GitHub Personal Access token, you can
[create one here](https://github.com/settings/tokens/new?description=name-your-contributors&scopes=read:org,user:email).
It needs to have the `read:org` and the `user:email` scopes in order to function
properly. Name the token something informative: `name-your-contributors` is a
good name.

Set the token with the variable name `$GITHUB_TOKEN` before running the script:

```sh
$ export GITHUB_TOKEN=ab34e...
```

You can also set the var automatically in every session by adding the above line
to your `.bashrc` file in your home directory.

The cost of querying a repo is approximately the number of PRs + the number of
issues + the number of comments with reactions (if querying reactions) + the
number of commits / 100 (if querying commit log).

So in the simplest case it's simply the total number of issues and PRs in the
repos being queried.

#### Caveats

GitHub regulates API traffic by a credit system. The limits are quite high; it's
permitted to query hundreds of repos per hour using the `repoContributors`
function, but some organisations have many hundreds of repos, and a single call
to `orgContributors` could potentially exhaust your entire hourly quota. The
WikiMedia Foundation is a good example of an org with way too many repos for
this app to handle.

Unfortunately filtering by contributions before or after a given date has no
effect on quota use, since the data still needs to be queried before it can be
filtered.

For more details on rate limits, see
https://developer.github.com/v4/guides/resource-limitations/.

## Usage

### From Code

```js
const nyc = require('name-your-contributors')

nyc.repoContributors({
token: process.env.GITHUB_TOKEN,
user: 'mntnr',
repo: 'name-your-contributors',
before: new Date(),
after: new Date(0)
}).then(
//do something with the results
)

nyc.orgContributors({
token: process.env.GITHUB_TOKEN,
orgName: 'ipfs',
before: '2017-01-01',
after: '2016-01-01'
}).then(...)
```

### From the Command Line

```sh
# Install the program
$ npm install -g name-your-contributors

# Make sure that a token is enabled - you can also save this in your .env
$ export GITHUB_TOKEN={your-token}

# Get all contributors to mntnr/name-your-contributors. Log to stdout.
$ name-your-contributors -u mntnr -r name-your-contributors

# Or, get all contributors to an org after a certain date, in a file
$ name-your-contributors -o ipfs -a 2017-01-01 > ipfs-contrib.json

# Use a config instead of specifying using CLI arguments - easier for repetitive use
$ name-your-contributors --config config.json > combined-out.json

# Print the help docs!
$ name-your-contributors --help

Name your GitHub contributors; get commits, issues, and comments

Usage
$ name-your-contributors [opts]

Options
-t, --token - GitHub auth token to use
-a, --after - Get contributions after date
-b, --before - Get contributions before data

-o, --org - Search all repos within this organisation
-r, --repo - Repository to search
-u, --user - User to which repository belongs
-c, --config - Operate from config file. In this mode only token, verbose, and
debug flags apply.

--full - Returns the full tree of contributions rather than the default
synopsis.
--csv - Output data in CSV format

--commits - Get commit authors and comments from GitHub
--local-dir - If specified, this script will look for repos being queried in
the provided dir and read the commit log from them directly.
--reactions - Query reactions of comments as well.

--wipe-cache - Wipe local cache before starting query.

-v, --verbose - Enable verbose logging
--debug - Enable extremely verbose logging
--dry-run - Check the cost of the query without executing it.

Authentication
This script looks for an auth token in the env var GITHUB_TOKEN. It needs
to have the read:org and the user:email scopes in order to function
properly. Make sure this var is set to a valid GitHub oauth token. To
create one see:
https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/
Examples
$ name-your-contributors -r ipfs -u ipfs --after=2016-01-15T00:20:24Z --before=2016-01-20T00:20:24Z

$ name-your-contributors -o ipfs -a 2017-01-01 > ipfs-contrib-2017.json

$ name-your-contributors --config config.json > combined-out.json
```

### Config File

For batching convenience, Name Your Contributors takes a config file which
specifies a token, a list of repos, and a list of orgs to grab. The
`config.json.example` is an outline of this file format:

```json
{
"token": "123435abcdf",
"repos": [{
"login": "mntnr",
"repo": "name-your-contributors",
"before": "2017-11-30",
"after": "2017-06-01"
}, {
"login": "mntnr",
"repo": "whodidwhat"
}],
"orgs": [{
"login": "adventure-js",
"after": "2017-07-01"
}]
}
```

A token passed in the config file will override any token present in the
environment.

The output when passed a config file is a mirror of the config file with the
token removed and a `contributions` key added to each object, like so:

```json
{
"repos": [{
"login": "mntnr",
"repo": "name-your-contributors",
"before": "2017-11-30",
"after": "2017-06-01",
"contributions" : {
"commitAuthors": [...],
"commitCommentators": [...],
,,,
},
...
}],
"orgs": [...]
}
```

The output will be in the format:

```sh
$ name-your-contributors -u mntnr -r name-your-contributors --after 2017-11-10

{
"commitAuthors": [],
"commitCommentators": [],
"prCreators": [],
"prCommentators": [
{
"login": "RichardLitt",
"name": "Richard Littauer",
"url": "https://github.com/RichardLitt",
"count": 3
},
{
"login": "tgetgood",
"name": "Thomas Getgood",
"url": "https://github.com/tgetgood",
"count": 2
}
],
"issueCreators": [
{
"login": "RichardLitt",
"name": "Richard Littauer",
"url": "https://github.com/RichardLitt",
"count": 1,
"titles": [
"Add example output to the README",
"Get email for users"
]
}
],
"issueCommentators": [
{
"login": "tgetgood",
"name": "Thomas Getgood",
"url": "https://github.com/tgetgood",
"count": 1
},
{
"login": "RichardLitt",
"name": "Richard Littauer",
"url": "https://github.com/RichardLitt",
"count": 1
}
],
"reactors": [
{
"login": "patcon",
"name": "Patrick Connolly",
"url": "https://github.com/patcon",
"count": 1
}
],
"reviewers": []
}
```

### Result formats

Name Your Contributors offers 4 distinct result formats intended for different
consumers.

#### Default

The default result format is an aggregate synopsis of all contributions in the
given time window. This is the format in the examples above.

#### CSV

With the `--csv` flag provided at the command line, nyc will return the default
info in CSV format rather than JSON.

#### Full Contribution Tree

If the `--full` flag is passed at the command line, then nyc will return the
full tree of org->repo->pr->comment->reaction->author for all interactions in
the given time window. This format is quite verbose, but invaluable if you want
to know not only who contributed, but the details of every contribution made.

For example,
```sh
$ name-your-contributors -r name-your-contributors -u mntnr -b 2017-12-10 -a 2017-11-10 --full
```
will return (abbreviated):
```sh
{
"repository": {
"homepageUrl": "",
"name": "name-your-contributors",
"owner": {
"login": "mntnr"
},
"pullRequests": [
{
"title": "Cli updates",
"number": 43,
"state": "MERGED",
"author": {
"login": "tgetgood",
"name": "Thomas Getgood",
"url": "https://github.com/tgetgood"
},
"createdAt": "2017-10-26T19:48:39Z",
"comments": [
{
"author": {
"login": "RichardLitt",
"name": "Richard Littauer",
"url": "https://github.com/RichardLitt"
},
"createdAt": "2017-11-20T16:35:31Z"
},
{
"author": {
"login": "tgetgood",
"name": "Thomas Getgood",
"url": "https://github.com/tgetgood"
},
"createdAt": "2017-11-21T21:05:15Z"
},
...
],
"reviews": []
},
...
]
}
}
```

Notice that the pull request above was created before the date passed to
before. It is still included because comments made within it were created in the
desired timeframe. If there had been no such comments, the PR would not be
included.

#### Condensed

For an even more condensed output format which also allows filtering on given
users, see the postprocessing script
[Who Did What](https://github.com/mntnr/whodidwhat).

## API

### orgContributors({orgName, token, before, after})

#### token

Type: `string`

Github auth token

#### org

Type: `string`

The organization to traverse. If no organization is provided, the script
will find the username and repo for the local git repository and use that.

#### opts.after

Type: `string`
Default value: `new Date(0)`

The ISO timestamp to get contributors after.

Any string that will be accepted by `new Date("...")` will work here as
expected.

#### opts.before

Type: `string`
Default value: `new Date()`

Get contributors from before this ISO timestamp.

### repoContributors({user, repo, token, before, after})

#### opts.user

Type: `string`

Github user name to whom the repo belongs.

#### opts.repo

Type: `string`

Only traverse the given repository.

## Development

There are several extra flags that are useful for development and diagnosing
issues:

`-v, --verbose` prints out each query that is sent to the api along with its
cost and the quota remaining after it is run.

`--debug` prints out each query sent to the server and the raw response. This is
extremely verbose.

`--dry-run` prints the cost of the first query that would have been run *without
running it*. Note that since the query isn't executed, follow up queries aren't
possible. when used with the `-c, --config` option, dry runs the first query for
each entry of the config file.

## Contribute

Name Your Contributors is an open source project - we'd love you to contribute! Check out the [Contributing document](CONTRIBUTING.md), and abide by the [Code of Conduct](CODE_OF_CONDUCT.md).

## License

[MIT](license) © 2018 [Richard Littauer](http://burntfen.com)