GitHub Readme Stats Ranking Algorithm: How S, A+, A, and B+ Grades Are Calculated

The GitHub Readme Stats ranking algorithm calculates grades by converting user activity metrics into a weighted percentile using cumulative distribution functions, then mapping that percentile to letter grades where S represents the top 1% and B+ covers the 37.5th to 50th percentile.

The ranking system displayed on GitHub Readme Stats cards is powered by a statistical model implemented in src/calculateRank.js. This article explains exactly how the GitHub Readme Stats ranking algorithm processes raw GitHub activity to assign S, A+, A, and B+ grades based on percentile thresholds.

How the Ranking Algorithm Works

At its core, the calculateRank function in src/calculateRank.js transforms six key metrics into a percentile score between 0 and 1, where lower values indicate higher rankings. The algorithm applies different statistical distributions to different metric types to account for power-law distributions in social metrics like stars versus linear activity metrics like commits.

Step 1: Input Parameters and Weights

The algorithm accepts an object containing raw GitHub statistics. Each metric has a default median value representing "average" activity and a weight reflecting its importance in the final score:

Metric	Default Median	Weight
Commits	250 (1000 if include_all_commits is true)	2
Pull Requests	50	3
Issues	25	1
Code Reviews	2	1
Stars	50	4
Followers	10	1

The total weight sum is 12. Stars carry the highest weight (4), followed by pull requests (3), making these metrics particularly influential for achieving high grades.

Step 2: Statistical Normalization with CDFs

To prevent outliers from skewing results, the algorithm normalizes each metric using cumulative distribution functions (CDFs). The raw count is divided by its median to create a ratio, then passed through the appropriate CDF.

For commits, pull requests, issues, and reviews, which follow exponential distributions, the algorithm uses:

const exponential_cdf = (x) => {
  return 1 - 2 ** -x;
};

For stars and followers, which follow power-law distributions where a small number of users accumulate extremely high values, the algorithm applies a log-normal CDF approximation:

const log_normal_cdf = (x) => {
  return x / (1 + x);
};

These functions map values to a scale between 0 and 1, with diminishing returns as values grow large.

Step 3: Weighted Percentile Calculation

The algorithm computes a weighted average of the normalized CDF values, then subtracts the result from 1 to produce a final percentile where lower values indicate better rankings:

const rank =
  1 -
  (COMMITS_WEIGHT * exponential_cdf(commits / COMMITS_MEDIAN) +
    PRS_WEIGHT * exponential_cdf(prs / PRS_MEDIAN) +
    ISSUES_WEIGHT * exponential_cdf(issues / ISSUES_MEDIAN) +
    REVIEWS_WEIGHT * exponential_cdf(reviews / REVIEWS_MEDIAN) +
    STARS_WEIGHT * log_normal_cdf(stars / STARS_MEDIAN) +
    FOLLOWERS_WEIGHT * log_normal_cdf(followers / FOLLOWERS_MEDIAN)) /
    TOTAL_WEIGHT;

The resulting rank variable represents the user's percentile relative to the defined medians.

Step 4: Grade Mapping

The final step converts the percentile to a letter grade using threshold boundaries defined in src/calculateRank.js:

const THRESHOLDS = [1, 12.5, 25, 37.5, 50, 62.5, 75, 87.5, 100];
const LEVELS = ["S", "A+", "A", "A-", "B+", "B", "B-", "C+", "C"];

The grade is selected by finding the first threshold greater than or equal to rank * 100:

Percentile Range	Grade
0% – 1%	S
1% – 12.5%	A+
12.5% – 25%	A
25% – 37.5%	A-
37.5% – 50%	B+
50% – 62.5%	B
62.5% – 75%	B-
75% – 87.5%	C+
87.5% – 100%	C

Implementation in src/calculateRank.js

You can import the ranking logic directly from the source to calculate grades for custom datasets:

import { calculateRank } from "./src/calculateRank.js";

const userStats = {
  all_commits: false,
  commits: 500,
  prs: 100,
  issues: 50,
  reviews: 20,
  repos: 0,
  stars: 200,
  followers: 40,
};

const { level, percentile } = calculateRank(userStats);
console.log(`Grade: ${level}, Percentile: ${percentile.toFixed(2)}%`);
// Output: Grade: A, Percentile: 20.84%

The function is thoroughly tested in tests/calculateRank.test.js, which validates expected grades for profiles ranging from new users to top contributors.

Summary

• The GitHub Readme Stats ranking algorithm uses a statistical model in src/calculateRank.js to convert raw activity metrics into percentiles.
• Six metrics (commits, PRs, issues, reviews, stars, followers) are normalized using exponential and log-normal cumulative distribution functions to handle power-law distributions.
• Weighted averaging (total weight 12) produces a final percentile where lower values indicate better rankings.
• Grade thresholds map percentiles to letter grades: S (top 1%), A+ (1–12.5%), A (12.5–25%), B+ (37.5–50%), down to C (bottom 12.5%).
• The calculateRank function can be imported directly for custom calculations or verified via the Jest test suite in tests/calculateRank.test.js.

Frequently Asked Questions

How does the GitHub Readme Stats ranking algorithm handle users with millions of stars?

The algorithm applies a log-normal cumulative distribution function (x / (1 + x)) to stars and followers, which creates diminishing returns for extremely high values. This prevents users with millions of stars from completely dominating the rankings compared to active contributors with moderate star counts but high commit activity.

What percentile do I need to achieve an S rank on my stats card?

To achieve an S rank, you must score in the top 1% of the calculated percentile (0% to 1%). Based on the algorithm's weights, this typically requires exceptional performance across all metrics, particularly high star counts (weight 4) and pull request activity (weight 3), placing you in the same tier as top GitHub power users like sindresorhus.

Does enabling "include all commits" affect my grade calculation?

Yes. When include_all_commits is set to true, the median value for commits changes from 250 to 1000 in the calculation. This means the same raw commit count will produce a lower relative score when compared against the higher median, making it more difficult to achieve high grades unless you have significantly more than 1000 total lifetime commits.

Where can I verify the ranking calculation for my specific GitHub stats?

You can verify the calculation by examining the calculateRank function in src/calculateRank.js and running the test suite in tests/calculateRank.test.js using Jest. The test file contains documented test cases for various user profiles, from new users (grade C) to expert contributors (grade A+), allowing you to compare your metrics against expected outputs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}