This project provides a helper tool to fetch contributor data sets for GitHub repositories and organizations using by extending the octokit/rest.js package.
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.
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.
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.
- 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.
If you are interested in contributing, please refer to the contributing document for more details. Thank you for being interested in improving the package!
Install with npm using npm install true-github-contributors
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.
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.
For developers to have an easier/quicker way to access the contribution data created through this mixin.
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.
JavaScript
Any JavaScript enviroment that is using octokit/rest.js.
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.
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.
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.
- Rewrite internal behaviour of methods to reduce code redundancy.
- Modify, update, add, and delete unit tests. Removed unit tests that seemed unnecessary.
- Remove
coverage/
directory from repository and add it to the.gitignore
file. - Add
SECURITY.md
,SUPPORT.md
, andCONTRIBUTING.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.
- Add License to npm package and Code of Conduct to GitHub repository.
- GitHub repository in package.json now points to the correct place.
- Endpoints that fetch any sort of commit contributions supply an empty array if a repository is empty instead of throwing an error.
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.
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
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.
Parameters: JSON object that reads the following
owner
: String login name of the owner of the repository.repo
: String repository name.[since]
: String ISO 8601 timestamp denoting which date to start fetching comments from.
Fetches GitHub contributors list for a repository with contributions based on the number of commits a user has made and sorts them by the number of commits per contributor in descending order.
Parameters: JSON object that reads the following
owner
: String login name of the owner of the repository.repo
: String repository name.[sha]
: String SHA or branch to start listing commits from. Default: the repository’s default branch.[path]
: String file path to fetch contributions only to this file.[since]
: String ISO 8601 timestamp denoting which date to start fetching commits from.[until]
: String ISO 8601 timestamp denoting which date to stop fetching commits before.
Fetches GitHub contributors list for a repository with contributions based on the number of issue comments and commits a user has made and sorts them by the number of total contributions per contributor in descending order.
Parameters: JSON object that reads the following
owner
: String login name of the owner of the repository.repo
: String repository name.[since]
: String ISO 8601 timestamp denoting which date to start fetching comments from.
Fetches contributors to a specified organization using octokit/rest
's native repos.listContributors
endpoint and sorts them by the number of commits per contributor in descending order.
Parameters: JSON object that reads the following
org
: String login name of the owner of the organization.type
: String type of repository to fetch from. Can be one ofall
,public
,private
,forks
,sources
,member
,internal
. Default:all
. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, type can also beinternal
.[anon]
: Boolean or Int to denote if anonymous contributors (no existing GitHub accounts associated with commit author email) should be included in results.
Fetches GitHub contributors list for an organization with contributions based on the number of commits a user has made and sorts them by the number of commits per contributor in descending order.
Parameters: JSON object that reads the following
org
: String login name of the owner of the organization.type
: String type of repository to fetch from. Can be one ofall
,public
,private
,forks
,sources
,member
,internal
. Default:all
. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, type can also beinternal
.[sha]
: String SHA or branch to start listing commits from. Default: the repository’s default branch.[path]
: String file path to fetch contributions only to this file.[since]
: String ISO 8601 timestamp denoting which date to start fetching commits from.[until]
: String ISO 8601 timestamp denoting which date to stop fetching commits before.
Fetches GitHub contributors list for an organization 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.
Parameters: JSON object that reads the following
org
: String login name of the owner of the organization.type
: String type of repository to fetch from. Can be one ofall
,public
,private
,forks
,sources
,member
,internal
. Default:all
. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, type can also beinternal
.[since]
: String ISO 8601 timestamp denoting which date to start fetching comments from.
Fetches GitHub contributors list for an organization with contributions based on the number of issue comments and commits a user has made and sorts them by the number of total contributions per contributor in descending order.
Parameters: JSON object that reads the following
org
: String login name of the owner of the organization.type
: String type of repository to fetch from. Can be one ofall
,public
,private
,forks
,sources
,member
,internal
. Default:all
. If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, type can also beinternal
.[since]
: String ISO 8601 timestamp denoting which date to start fetching comments from.