Contributor Data Directory

This directory contains YAML data files that power the gamified character profile system for IT-Journey contributors.

How It Works

Each contributor has a {username}.yml file with two zones:

1. User-Editable Zone (profile:) — Customize your display name, avatar, class, bio, links, and pinned badges.
2. Auto-Generated Zone (stats:, achievements:, level:) — Computed from git history and content files. Overwritten automatically on each push to main.

Adding a New Contributor

1. Copy _template.yml to {your-github-username}.yml
2. Fill in the profile: section
3. Leave stats:, achievements:, and level: sections as-is (they'll be populated by CI)
4. Create your profile page at pages/_about/contribute/contributors/{username}/README.md
5. Submit a PR

Data Schema

profile (user-editable)

Field	Type	Description
display_name	string	Your display name
avatar	string	Path to avatar image (fallback: https://github.com/{username}.png)
class	string	RPG class: Wizard, Warrior, Ranger, Healer, Rogue, Bard
title	string	Your title or role
bio	string	Short bio
location	string	Where you're based
motto	string	Personal motto
banner_color	string	Hex color for profile banner (optional)
links	map	github, twitter, linkedin, website
badges_pinned	list	Up to 5 achievement IDs to feature prominently

stats (auto-generated)

Field	Type	Description
total_commits	int	Total commits to the repository
total_prs_merged	int	Pull requests merged
total_quests_authored	int	Quests where contributor is author
total_posts_authored	int	Posts where contributor is author
lines_added	int	Total lines added
lines_removed	int	Total lines removed
first_contribution_date	date	Date of first commit
latest_contribution_date	date	Date of most recent commit
active_days	int	Number of unique days with commits
streak_days	int	Current consecutive-day commit streak
top_languages	list	Top 5 languages by file extension
top_categories	list	Top 5 content categories
contribution_calendar	list	Weekly commit counts (last 52 weeks)

achievements (auto-generated)

Array of earned badges:

Field	Type	Description
id	string	Unique achievement identifier
name	string	Display name
icon	string	Emoji icon
description	string	How to earn this achievement
earned_date	date	When it was earned

level (auto-generated)

Field	Type	Description
xp	int	Total experience points
current_level	string	Binary level (0000-1111)
tier	string	Apprentice / Adventurer / Warrior / Master
xp_to_next_level	int	XP remaining
progress_percent	int	Progress bar percentage

XP Formula

Activity	XP
Commit	10
PR Merged	50
Quest Authored	200
Post Authored	100

Level = floor(log2(xp / 100)) clamped to 0–15 (maps to binary 0000–1111).

Achievement Catalog

ID	Name	Icon	Condition
first_blood	First Blood	⚔️	First commit
ten_commits	Dedicated	🔟	10 commits
centurion	Centurion	💯	100 commits
quest_forger	Quest Forger	🏰	First quest authored
chronicler	Chronicler	📜	First post authored
five_posts	Prolific Writer	✍️	5 posts authored
marathon_runner	Marathon Runner	🏃	7-day commit streak
guild_founder	Guild Founder	🏛️	500+ commits (founder-level)
polyglot	Polyglot	🌐	Commits touching 5+ languages
streak_master	Streak Master	🔥	30-day commit streak

Regenerating Stats

# Single contributor
make contributor-stats USERNAME=bamr87

# All contributors
make contributor-stats-all

Stats are also auto-regenerated by GitHub Actions on every push to main.

Files

File	Purpose
_template.yml	Blank template — copy to create your profile
bamr87.yml	Contributor data for bamr87
README.md	This documentation