True GitHub Contributors

Overview

This project provides a helper tool to fetch contributor data sets for GitHub repositories and organizations using by extending the octokit/rest.js package.

Problem Being Solved

On the Hack for LA website we wanted to show all Project team contributors (not just people who commit code). In order to do that we needed to capture the contributions made by those who provide content (images, comments) on issues. GitHub currently does not have this as an aggregated endpoint.

Value Created from Solution

The benefit of including issue comments in contribution data is that a more complete data set of contributors is given. With GitHub having features like project boards and issue comments, GitHub has opened up more ways for different roles to contribute code. Designers post screenshots of mock ups, project managers communicate critical information to team members, and even developers have productive discussions about the code they are writing. By including these comments as contributions, a clearer picture of who is/has been active in the project is shown.

Solution (simplified explanation):

We created a script that

Fetched the data from the GitHub API Repository Contributors endpoint which returns a pre deduped list of all GithHub handles from code commits and the number of contributions.
Fetched the data from the GitHub API Repository Issue Comments endpoint which returns all issue comments in a repository
Created a list a list of handles and number of contributions to entire repository (same format as the contributors api).
Aggregated the responses from the two lists.

There is more to it then the above, e.g. how to deal with pagination of results issues, etc. read below for more technical details.

This repo/tool also makes use of the octokit/rest.js package and then extends it.

Stakeholders

Project Leadership: Able to see who is contributing to repositories and organizations.
Project contributors: Efforts made through issue comments will be reflected in contributor sets.

Contributing

If you are interested in contributing, please refer to the contributing document for more details. Thank you for being interested in improving the package!

Technical Details

Installation

Install with npm using npm install true-github-contributors

Current State

Currently, the Hack for LA website uses GitHub Actions to run a script. The script uses a HTTP request library to make calls to the API directly and performs the aggregation of the data in way that could be cleaner.

In this repository, I have developed a mixin for octokit/rest.js that fetches the desired data sets and more. This will allow users of the mixin to still use octokit/rest.js as they normally do and extend it's functionality with a minimal footprint.

The mixin uses octokit/rest's pagination endpoint to fetch relevant commit/issue comment data. Because commit/issue comment data can be large, this results in long wait times for the paginate endpoint to return commit/issue comment data. This, in turn, results in the endpoints of this mixin to have long wait times when the specified repository/organization has large amounts of commits/issue comments. Please keep this in mind if it is necessary for your project to be as fast as possible.

Future Development

The endpoints created with this mixin are currently being tested. I would also like this mixin to be available through npm. This would make the process of using the mixin more convenient for those in node environments.

Anticipated technical outcomes

For developers to have an easier/quicker way to access the contribution data created through this mixin.

Resources/Instructions

See API documentaion below for documentation on how to use the API. If you would like to see usage examples for each of the API endpoints, refer to the examples directory in this repo.

Language

JavaScript

Platform

Any JavaScript enviroment that is using octokit/rest.js.

Automation triggers

Because this is an extension of octokit/rest.js, it is used in a way that is identical to octokit/rest.js. That is, the API Client can be used in single use scripts, automated scripts, or in any JavaScript environment.

Input required

The goal of this mixin is to make it feel like it's naturally a part of octokit/rest.js. Because of that, it also takes input similarly to how octokit/rest.js: a set of parameters that define the desired organiation/repo and additional parameters to further define what you want the data set to represent. In the future, there will be detailed documentation on how to use the mixin.

Output

Each of the endpoints will return an arraay of contributor objects that mimic the structure of the "List Repository Contributors" endpoint of the GitHub API:

{
    login: 'KianBadie',
    id: 18221058,
    node_id: 'MDQ6VXNlcjE4MjIxMDU4',
    avatar_url: 'https://avatars1.githubusercontent.com/u/18221058?v=4',
    gravatar_id: '',
    url: 'https://api.github.com/users/KianBadie',
    html_url: 'https://github.com/KianBadie',
    followers_url: 'https://api.github.com/users/KianBadie/followers',
    following_url: 'https://api.github.com/users/KianBadie/following{/other_user}',
    gists_url: 'https://api.github.com/users/KianBadie/gists{/gist_id}',
    starred_url: 'https://api.github.com/users/KianBadie/starred{/owner}{/repo}',
    subscriptions_url: 'https://api.github.com/users/KianBadie/subscriptions',
    organizations_url: 'https://api.github.com/users/KianBadie/orgs',
    repos_url: 'https://api.github.com/users/KianBadie/repos',
    events_url: 'https://api.github.com/users/KianBadie/events{/privacy}',
    received_events_url: 'https://api.github.com/users/KianBadie/received_events',
    type: 'User',
    site_admin: false,
    contributions: 160
  }

Every user object will have additional endpoints that can give more data about each contributor, as well as a contribution property that represents the number of contributions a user has made to a repository or organization.

API

Versions/Updates

Version `1.0.5` Changes

Rewrite internal behaviour of methods to reduce code redundancy.
Modify, update, add, and delete unit tests. Removed unit tests that seemed unnecessary.

Version `1.0.4` Changes

Remove coverage/ directory from repository and add it to the .gitignore file.
Add SECURITY.md, SUPPORT.md, and CONTRIBUTING.md to the .npmignore file so that they will not be included with package installation.
Add "Contributing" section to readme and modify the "Configuration" and "Usage" sections of the readme to be part of a new "Getting Started" section that has more details.

Version `1.0.3` Changes

Add License to npm package and Code of Conduct to GitHub repository.

Version `1.0.2` Changes

GitHub repository in package.json now points to the correct place.

Version `1.0.1` Changes

Endpoints that fetch any sort of commit contributions supply an empty array if a repository is empty instead of throwing an error.

Getting Started

Configuration

As mentioned previously, this mixin is an extension of GitHub's octokit/rest.js API Client. In order to use the features of this mixin, the octokit/rest.js package is required.

Once octokit/rest and true-github-contributors are installed, the methods of the true-github-contributors mixin must be copied into the Octokit prototype in order to be used (see code snippet below). For an intro on what mixins are in JavaScript and how they are implemented, see JavaScript.info's "Mixins" article.

require("dotenv").config();
const { Octokit } = require("@octokit/rest");
const trueGitHubContributors = require("true-github-contributors");

Object.assign(Octokit.prototype, trueGitHubContributors);
const octokit = new Octokit({ auth: process.env.token });

Once the mixin is merged with the Octokit prototype, a new instance of the Octokit class must be instantiated (as seen in the last line of the code snippet above). This will allow one to start using the methods of the Octokit class (for usage of the Octokit class, please refer to Octokit's documenation) as well as the methods of the true-github-contributors mixin. A short example of usage is show below in the Usage section. Examples of every API endpoint of the true-github-contributors mixin in different use cases are available in the examples directory.

While using an API token to construct an Octokit instance is not required, I highly recommend it with the use of this mixin (like I did in the above code snippet). Endpoints that access data like commits and comments have the potentional of fetching a large amount of data. Using an API token will decrease the chances of you exceeding the GitHub API rate limits.

Usage

The endpoints of the mixin are accessed a bit differently than how endpoints are normally accessed with octokit/rest. API endpoints are called directly on the octokit object, as in:

octokit.listCommitContributors(parameters) // Mixin endpoint for fetching commit contributors
octokit.listContributorsForOrg(parameters) // Mixin endpoint for fetching contributors across an organization

As opposed to octokit/rest, where endpoints are nested into property specific groupings

octokit.repos.listContributors(parameters) // Octokit endpoint for fetching contributors
octokit.repos.listForOrg(parameters) // Octokit endpoint for fetching repos in an organization

Endpoint Documentation

`listCommentContributors(parameters)`

Fetches GitHub contributors list for a repository with contributions based on the number of issue comments a user has made and sorts them by the number of issue comments per contributor in descending order.