From dfccce315c23566bfa17cd11b27b84851c845490 Mon Sep 17 00:00:00 2001 From: Lukasz Raczylo Date: Thu, 11 Dec 2025 13:04:58 +0000 Subject: [PATCH] Update documentation page, add scoring calculations. --- docs/calculations.html | 819 +++++++++++++++++++++++++++++++++++++++++ docs/index.html | 48 +-- 2 files changed, 844 insertions(+), 23 deletions(-) create mode 100644 docs/calculations.html diff --git a/docs/calculations.html b/docs/calculations.html new file mode 100644 index 0000000..09d1dc6 --- /dev/null +++ b/docs/calculations.html @@ -0,0 +1,819 @@ + + + + + + How Scoring Works - Git Velocity + + + + + + + + + + + + + + + + + + + + +
+
+
+
+

+ How Scoring Works +

+

+ Understanding the point system, leaderboard rankings, and achievement criteria that power Git Velocity. +

+
+
+
+ + +
+
+
+
+

+ + Overview +

+

+ Git Velocity calculates developer contributions by analyzing GitHub activity across configured repositories. + The scoring system is designed to encourage well-rounded contributions including code commits, pull requests, + code reviews, and collaboration. +

+
+
+ +

Point-Based

+

Activities earn configurable points

+
+
+ +

Aggregated

+

Combined across all repositories

+
+
+ +

Achievement-Driven

+

Unlock badges for milestones

+
+
+
+
+
+
+ + +
+
+
+

Point Calculations

+

How each activity contributes to your score

+
+
+ +
+

+ + Score Formula +

+
+ 
Total Score = Commits + Line Changes + PRs + Reviews + Comments + Response Bonus + Out of Hours
+
+Where:
+  Commits      = commit_count × 10 points
+  Line Changes = (lines_added × 0.1) + (lines_deleted × 0.05) points
+  PRs          = (PRs_opened × 25) + (PRs_merged × 50) points
+  Reviews      = reviews_given × 30 points
+  Comments     = review_comments × 5 points
+  Response     = bonus for fast review response (0-50 points)
+  Out of Hours = commits outside 9am-5pm × 2 points
+
+

+ + All point values are configurable in your .git-velocity.yaml file. +

+
+ + +
+

+ + Default Point Values +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ActivityPointsDescription
Commit10Per commit pushed
Commit with Tests15Commit that includes test files
Lines Added0.1Per meaningful line added
Lines Deleted0.05Per meaningful line removed
PR Opened25Per pull request created
PR Merged50Per pull request merged
PR Reviewed30Per PR review submitted
Review Comment5Per comment on PR reviews
Fast Review (<1h)50Bonus for average response under 1 hour
Fast Review (<4h)25Bonus for average response under 4 hours
Fast Review (<24h)10Bonus for average response under 24 hours
Out of Hours2Per commit outside 9am-5pm
+
+
+ + +
+

+ + Meaningful Lines +

+

+ By default, Git Velocity uses meaningful lines instead of raw line counts. + This filters out noise and rewards actual code contributions: +

+
+
+

+ Counted as Meaningful +

+
    +
  • Actual code logic
    • +
  • Function definitions
    • +
  • Variable declarations
    • +
  • Import statements
    • +
+
+
+

+ Filtered Out +

+
    +
  • Empty lines / whitespace
    • +
  • Single-line comments
    • +
  • Multi-line comment blocks
    • +
  • Documentation strings
    • +
+
+
+

+ + Disable with use_meaningful_lines: false in config to use raw line counts. +

+
+
+
+
+ + +
+
+
+

Leaderboard Rankings

+

How positions are determined

+
+
+ +
+

+ + Ranking Process +

+
    +
  1. + 1 +
    +

    Aggregate Across Repos

    +

    Metrics from all configured repositories are combined per contributor

    +
    +
    2. +
  2. + 2 +
    +

    Calculate Total Score

    +

    Apply point values to each activity type and sum the breakdown

    +
    +
    3. +
  3. + 3 +
    +

    Sort by Score

    +

    Contributors are sorted in descending order by total score

    +
    +
    4. +
  4. + 4 +
    +

    Assign Ranks & Percentiles

    +

    Each contributor receives a rank (1st, 2nd...) and percentile position

    +
    +
    5. +
+
+ + +
+

+ + Top Achievers +

+

+ Git Velocity tracks top performers in each category: +

+
+
+
+ + Overall Leader +
+

Highest total score

+
+
+
+ + Top Committer +
+

Most commits

+
+
+
+ + Top Reviewer +
+

Most reviews given

+
+
+
+ + Top PR Author +
+

Most PRs opened

+
+
+
+ + +
+

+ + Team Scoring +

+

+ When teams are configured, Git Velocity calculates team metrics: +

+
    +
  • Total Team Score: Sum of all member scores
    • +
  • Average Score: Total score / number of members
    • +
  • Member Breakdown: Individual scores and achievements per team member
    • +
+
+
+
+
+ + +
+
+
+

Achievement System

+

95 achievements across 22 categories with tiered progression

+
+
+ +
+

+ + Achievement Categories +

+
+ +
+

+ Commits +

+

Tiers: 1, 10, 50, 100, 500, 1000

+
+ First Steps → Getting Started → Contributor → Committed → Code Machine → Code Warrior +
+
+ +
+

+ PRs Opened +

+

Tiers: 1, 10, 25, 50, 100, 250

+
+ PR Pioneer → PR Regular → PR Pro → Merge Master → PR Champion → PR Legend +
+
+ +
+

+ Reviews Given +

+

Tiers: 1, 10, 25, 50, 100, 250

+
+ First Review → Reviewer → Review Regular → Review Expert → Review Guru → Review Master +
+
+ +
+

+ Review Comments +

+

Tiers: 10, 50, 100, 250, 500

+
+ Commentator → Feedback Giver → Code Critic → Feedback Expert → Comment Champion +
+
+ +
+

+ Lines Added +

+

Tiers: 100, 1K, 5K, 10K, 50K

+
+ First Hundred → Thousand Lines → Five Thousand → Ten Thousand → Code Mountain +
+
+ +
+

+ Lines Deleted +

+

Tiers: 100, 500, 1K, 5K, 10K

+
+ Tidying Up → Spring Cleaning → Code Cleaner → Refactoring Hero → Deletion Master +
+
+ +
+

+ Response Time +

+

Tiers: <24h, <4h, <1h

+
+ Same Day Reviewer → Quick Responder → Speed Demon +
+
+ +
+

+ Contribution Streaks +

+

Tiers: 3, 7, 14, 30 days

+
+ Getting Rolling → Week Warrior → Two Week Streak → Month Master +
+
+ +
+

+ Activity Patterns +

+

Early Bird, Night Owl, Weekend Warrior

+
+ Commits at different times of day unlock special badges +
+
+
+
+ + +
+

+ + How Achievements Are Earned +

+

+ Each achievement has a condition type and threshold. + When your metrics meet or exceed the threshold, the achievement is unlocked. +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Condition TypeMetric CheckedComparison
commit_countTotal commits≥ threshold
pr_opened_countPRs opened≥ threshold
review_countReviews given≥ threshold
avg_review_time_hoursAverage review response≤ threshold (lower is better)
longest_streakConsecutive active days≥ threshold
perfect_prsPRs with no changes requested≥ threshold
repo_countRepositories contributed to≥ threshold
+
+

+ + Achievement definitions are hardcoded and cannot be customized to prevent manipulation. +

+
+ + +
+

+ + Tiered Progression +

+

+ Most achievements have multiple tiers. As you progress, you unlock higher tiers: +

+
+ Tier 1: 1 + Tier 2: 10 + Tier 3: 25 + Tier 4: 50 + Tier 5: 100 + Tier 6: 250 + Tier 7: 500 + Tier 8+: 1000+ +
+

+ The leaderboard shows only the highest tier achieved per category for each contributor. +

+
+
+
+
+ + +
+
+
+

Data Sources

+

Where the metrics come from

+
+
+
+

+ + GitHub API Data +

+
+
+

Commits

+
    +
  • SHA, message, timestamp
    • +
  • Author (login, name, email)
    • +
  • Additions, deletions, files changed
    • +
  • Patch/diff for line analysis
    • +
+
+
+

Pull Requests

+
    +
  • State (open, merged, closed)
    • +
  • Author and timestamps
    • +
  • Size (additions, deletions)
    • +
  • Comments count
    • +
+
+
+

Reviews

+
    +
  • Review state (approved, changes requested)
    • +
  • Reviewer login
    • +
  • Submission timestamp
    • +
  • Comment count
    • +
+
+
+

User Profiles

+
    +
  • GitHub login (username)
    • +
  • Display name
    • +
  • Avatar URL
    • +
  • Public email (for deduplication)
    • +
+
+
+
+ + +
+

+ + Derived Metrics +

+

+ These metrics are calculated from raw data: +

+
+
+ Meaningful Lines +

Parsed from commit diffs, filtering comments/whitespace

+
+
+ Average Review Time +

Time between PR creation and first review

+
+
+ Contribution Streaks +

Consecutive days with activity

+
+
+ Perfect PRs +

PRs merged without "changes requested" reviews

+
+
+ Out of Hours +

Commits outside 9am-5pm based on commit timestamp

+
+
+ Unique Reviewees +

Count of distinct PR authors reviewed

+
+
+
+ + +
+

+ + Bot Filtering +

+

+ By default, bot activity is excluded from metrics. The following patterns are automatically filtered: +

+
+ *[bot] + dependabot* + renovate* + github-actions* + codecov* + snyk* + greenkeeper* +
+

+ + Enable with include_bots: true or add custom patterns with additional_bot_patterns. +

+
+
+
+
+ + +
+
+

Ready to Track Your Velocity?

+

Now that you understand how scoring works, start analyzing your repositories.

+
+ + Get Started + + + Configure Points + +
+
+
+ + + + + + + diff --git a/docs/index.html b/docs/index.html index 2b3adeb..7184fc0 100644 --- a/docs/index.html +++ b/docs/index.html @@ -112,37 +112,39 @@ Git Velocity - -