Opinion: Senior Developers Should Mentor Juniors in 2026 – It's Good for Your Career

# mentorship_tracker.py
# A CLI tool for senior engineers to log, track, and report on mentorship sessions with juniors
# Requires Python 3.11+, uses standard library only for portability
# Data persisted to ~/.mentorship_sessions.json

import json
import os
import sys
from datetime import datetime, timedelta
from typing import List, Dict, Optional

DEFAULT_STORAGE_PATH = os.path.expanduser('~/.mentorship_sessions.json')
REQUIRED_SESSION_FIELDS = ['junior_name', 'date', 'duration_mins', 'topics', 'outcome']

class MentorshipTracker:
    def __init__(self, storage_path: str = DEFAULT_STORAGE_PATH):
        self.storage_path = storage_path
        self.sessions = self._load_sessions()

    def _load_sessions(self) -> List[Dict]:
        \"\"\"Load existing sessions from JSON storage, handle missing/corrupt files\"\"\"
        if not os.path.exists(self.storage_path):
            return []
        try:
            with open(self.storage_path, 'r') as f:
                data = json.load(f)
                if not isinstance(data, list):
                    raise ValueError('Storage file contains invalid data format')
                return data
        except (json.JSONDecodeError, ValueError) as e:
            print(f'Warning: Could not load sessions from {self.storage_path}: {e}', file=sys.stderr)
            # Backup corrupt file before resetting
            backup_path = f'{self.storage_path}.backup.{datetime.now().strftime(\"%Y%m%d%H%M%S\")}'
            os.rename(self.storage_path, backup_path)
            print(f'Corrupt storage backed up to {backup_path}', file=sys.stderr)
            return []

    def _save_sessions(self) -> None:
        \"\"\"Persist sessions to JSON storage with error handling\"\"\"
        try:
            with open(self.storage_path, 'w') as f:
                json.dump(self.sessions, f, indent=2)
        except IOError as e:
            print(f'Error: Could not save sessions to {self.storage_path}: {e}', file=sys.stderr)
            sys.exit(1)

    def log_session(self, junior_name: str, duration_mins: int, topics: List[str], outcome: str, date: Optional[str] = None) -> None:
        \"\"\"Log a new mentorship session with validation\"\"\"
        if duration_mins <= 0 or duration_mins > 240:
            raise ValueError(f'Duration must be between 1 and 240 minutes, got {duration_mins}')
        if not topics:
            raise ValueError('At least one topic must be specified')

        session_date = date if date else datetime.now().strftime('%Y-%m-%d')
        # Validate date format
        try:
            datetime.strptime(session_date, '%Y-%m-%d')
        except ValueError:
            raise ValueError(f'Invalid date format: {session_date}. Use YYYY-MM-DD')

        session = {
            'junior_name': junior_name,
            'date': session_date,
            'duration_mins': duration_mins,
            'topics': topics,
            'outcome': outcome,
            'logged_at': datetime.now().isoformat()
        }
        self.sessions.append(session)
        self._save_sessions()
        print(f'Logged session with {junior_name} on {session_date}')

    def generate_report(self, days: int = 90) -> Dict:
        \"\"\"Generate a report of mentorship activity over the last N days\"\"\"
        cutoff = datetime.now() - timedelta(days=days)
        recent_sessions = []
        for s in self.sessions:
            try:
                session_date = datetime.strptime(s['date'], '%Y-%m-%d')
                if session_date >= cutoff:
                    recent_sessions.append(s)
            except KeyError:
                continue  # Skip malformed sessions

        total_duration = sum(s['duration_mins'] for s in recent_sessions)
        unique_juniors = len(set(s['junior_name'] for s in recent_sessions))
        return {
            'period_days': days,
            'total_sessions': len(recent_sessions),
            'total_duration_mins': total_duration,
            'unique_juniors': unique_juniors,
            'avg_session_mins': total_duration / len(recent_sessions) if recent_sessions else 0
        }

def main():
    tracker = MentorshipTracker()
    if len(sys.argv) < 2:
        print('Usage: python mentorship_tracker.py [log|report]')
        print('  log: Log a new session (will prompt for inputs)')
        print('  report: Generate activity report (optionally pass --days N)')
        sys.exit(0)

    command = sys.argv[1]
    if command == 'log':
        try:
            junior = input('Junior engineer name: ')
            duration = int(input('Session duration (minutes): '))
            topics_input = input('Topics covered (comma-separated): ')
            topics = [t.strip() for t in topics_input.split(',') if t.strip()]
            outcome = input('Session outcome: ')
            tracker.log_session(junior, duration, topics, outcome)
        except ValueError as e:
            print(f'Input error: {e}', file=sys.stderr)
            sys.exit(1)
    elif command == 'report':
        days = 90
        if '--days' in sys.argv:
            idx = sys.argv.index('--days')
            if idx + 1 < len(sys.argv):
                try:
                    days = int(sys.argv[idx + 1])
                except ValueError:
                    print(f'Invalid days value: {sys.argv[idx+1]}', file=sys.stderr)
                    sys.exit(1)
        report = tracker.generate_report(days)
        print(json.dumps(report, indent=2))
    else:
        print(f'Unknown command: {command}', file=sys.stderr)
        sys.exit(1)

if __name__ == '__main__':
    main()

# mentorship_pairer.py
# Algorithm to pair senior engineers with junior mentees based on skill gaps, availability, and learning goals
# Uses data from GitHub API (via PyGithub) and Linear (via linear-api-client 2026.1)
# Requires environment variables: GITHUB_TOKEN, LINEAR_API_KEY

import os
import sys
from datetime import datetime, timedelta
from typing import List, Dict, Tuple, Optional
from collections import defaultdict

try:
    from github import Github, GithubException
    from linear import LinearClient, LinearException
except ImportError as e:
    print(f'Missing dependency: {e}. Install with: pip install pygithub linear-api-client==2026.1', file=sys.stderr)
    sys.exit(1)

# Configuration
SENIOR_ROLE_KEYWORDS = ['senior', 'staff', 'principal']
JUNIOR_ROLE_KEYWORDS = ['junior', 'associate', 'new grad']
MAX_PAIRING_DIFFERENCE = 2  # Max skill level difference between senior and junior
MIN_WEEKLY_MENTORSHIP_HOURS = 1
MAX_WEEKLY_MENTORSHIP_HOURS = 4

class MentorshipPairer:
    def __init__(self):
        self.github_token = os.getenv('GITHUB_TOKEN')
        self.linear_api_key = os.getenv('LINEAR_API_KEY')
        if not self.github_token:
            raise ValueError('GITHUB_TOKEN environment variable not set')
        if not self.linear_api_key:
            raise ValueError('LINEAR_API_KEY environment variable not set')

        self.github_client = Github(self.github_token)
        self.linear_client = LinearClient(self.linear_api_key)
        self.seniors = []
        self.juniors = []

    def _fetch_team_members(self, org_name: str, team_name: str) -> List[Dict]:
        \"\"\"Fetch team members from Linear and cross-reference with GitHub org\"\"\"
        try:
            # Fetch Linear team members
            linear_team = self.linear_client.team(team_name)
            linear_members = [m for m in linear_team.members() if m.active]

            # Fetch GitHub org members
            github_org = self.github_client.get_organization(org_name)
            github_members = [m.login for m in github_org.get_members()]

            # Merge data
            team_members = []
            for lm in linear_members:
                # Match Linear user to GitHub by email prefix (simplified for example)
                github_username = None
                if lm.email:
                    prefix = lm.email.split('@')[0]
                    if prefix in github_members:
                        github_username = prefix

                team_members.append({
                    'linear_id': lm.id,
                    'name': lm.name,
                    'email': lm.email,
                    'role': lm.role.lower(),
                    'github_username': github_username,
                    'active': lm.active
                })
            return team_members
        except (LinearException, GithubException) as e:
            print(f'Error fetching team data: {e}', file=sys.stderr)
            raise

    def categorize_members(self, org_name: str, team_name: str) -> None:
        \"\"\"Categorize team members into seniors and juniors based on role keywords\"\"\"
        members = self._fetch_team_members(org_name, team_name)
        for m in members:
            role = m['role']
            if any(kw in role for kw in SENIOR_ROLE_KEYWORDS):
                self.seniors.append(m)
            elif any(kw in role for kw in JUNIOR_ROLE_KEYWORDS):
                self.juniors.append(m)
        print(f'Categorized {len(self.seniors)} seniors, {len(self.juniors)} juniors')

    def _get_skill_gap(self, senior: Dict, junior: Dict) -> Optional[int]:
        \"\"\"Calculate skill gap between senior and junior using GitHub contribution data\"\"\"
        if not senior['github_username'] or not junior['github_username']:
            return None  # Can't calculate without GitHub data
        try:
            senior_user = self.github_client.get_user(senior['github_username'])
            junior_user = self.github_client.get_user(junior['github_username'])

            # Calculate contribution score: stars + forks + commits (last 6 months)
            def get_contribution_score(user):
                repos = user.get_repos(type='owner', sort='pushed')
                total = 0
                six_months_ago = datetime.now() - timedelta(days=180)
                for repo in repos:
                    if repo.pushed_at < six_months_ago:
                        continue
                    total += repo.stargazers_count * 2
                    total += repo.forks_count * 1
                    # Get commit count (simplified, skips pagination for example)
                    commits = repo.get_commits(author=user)
                    total += commits.totalCount * 0.5
                return total

            senior_score = get_contribution_score(senior_user)
            junior_score = get_contribution_score(junior_user)
            return int(senior_score - junior_score)
        except GithubException:
            return None

    def generate_pairings(self) -> List[Tuple[Dict, Dict]]:
        \"\"\"Generate optimal mentorship pairings based on skill gaps\"\"\"
        if not self.seniors or not self.juniors:
            raise ValueError('No seniors or juniors categorized. Run categorize_members first.')

        # Calculate skill gaps for all possible pairs
        pair_scores = defaultdict(dict)
        for s in self.seniors:
            for j in self.juniors:
                gap = self._get_skill_gap(s, j)
                if gap is not None and 0 < gap <= MAX_PAIRING_DIFFERENCE:
                    pair_scores[s['linear_id']][j['linear_id']] = gap

        # Greedy pairing: match juniors to seniors with smallest gap first
        paired_juniors = set()
        paired_seniors = set()
        pairings = []

        # Flatten and sort pairs by gap ascending
        all_pairs = []
        for s_id, j_dict in pair_scores.items():
            for j_id, gap in j_dict.items():
                all_pairs.append((gap, s_id, j_id))
        all_pairs.sort()

        for gap, s_id, j_id in all_pairs:
            # Find senior and junior objects
            senior = next(s for s in self.seniors if s['linear_id'] == s_id)
            junior = next(j for j in self.juniors if j['linear_id'] == j_id)

            # Check if senior is already paired (simplified: 1 junior per senior for example)
            if s_id in paired_seniors or j_id in paired_juniors:
                continue

            pairings.append((senior, junior))
            paired_seniors.add(s_id)
            paired_juniors.add(j_id)

            if len(paired_juniors) == len(self.juniors):
                break  # All juniors paired

        return pairings

def main():
    try:
        pairer = MentorshipPairer()
        # Example org and team: replace with your own
        pairer.categorize_members(org_name='my-org', team_name='backend')
        pairings = pairer.generate_pairings()

        print(f'Generated {len(pairings)} mentorship pairings:')
        for senior, junior in pairings:
            print(f'  Senior: {senior[\"name\"]} <-> Junior: {junior[\"name\"]}')

        # Output to JSON for integration with HR tools
        output = [{'senior_id': s['linear_id'], 'junior_id': j['linear_id']} for s, j in pairings]
        with open('mentorship_pairings.json', 'w') as f:
            json.dump(output, f, indent=2)
        print('Pairings saved to mentorship_pairings.json')
    except Exception as e:
        print(f'Fatal error: {e}', file=sys.stderr)
        sys.exit(1)

if __name__ == '__main__':
    main()

# mentorship_metrics_exporter.py
# Prometheus exporter for mentorship program metrics, to be scraped by Grafana for team dashboards
# Exposes metrics: mentorship_sessions_total, mentorship_duration_mins_total, mentorship_juniors_supported_total
# Requires: prometheus-client==0.21.1, uses the MentorshipTracker from first example

import time
import sys
import os
import json
from prometheus_client import start_http_server, Gauge, Counter
from typing import Dict

# Reuse storage path from MentorshipTracker
DEFAULT_STORAGE_PATH = os.path.expanduser('~/.mentorship_sessions.json')
try:
    from mentorship_tracker import MentorshipTracker
except ImportError:
    print('Error: mentorship_tracker.py not found in path. Copy it to the same directory.', file=sys.stderr)
    sys.exit(1)

# Define Prometheus metrics
MENTORSHIP_SESSIONS_TOTAL = Counter(
    'mentorship_sessions_total',
    'Total number of mentorship sessions logged',
    ['junior_name', 'senior_name']
)
MENTORSHIP_DURATION_MINS_TOTAL = Counter(
    'mentorship_duration_mins_total',
    'Total duration of mentorship sessions in minutes',
    ['junior_name', 'senior_name']
)
MENTORSHIP_JUNIORS_SUPPORTED = Gauge(
    'mentorship_juniors_supported_total',
    'Total number of unique juniors supported by a senior',
    ['senior_name']
)
MENTORSHIP_AVG_SESSION_MINS = Gauge(
    'mentorship_avg_session_mins',
    'Average duration of mentorship sessions per senior',
    ['senior_name']
)

def update_metrics(tracker: MentorshipTracker, senior_name: str) -> None:
    \"\"\"Update Prometheus metrics from mentorship session data\"\"\"
    # Reset metrics for this senior to avoid stale data
    MENTORSHIP_SESSIONS_TOTAL.labels(junior_name='', senior_name=senior_name)._value.set(0)
    MENTORSHIP_DURATION_MINS_TOTAL.labels(junior_name='', senior_name=senior_name)._value.set(0)

    # Filter sessions for this senior (simplified: assume junior_name is tracked, senior is current user)
    # In real use, you'd track senior per session; this is a simplified example
    senior_sessions = [s for s in tracker.sessions if True]  # Replace with actual senior filter

    # Group by junior
    junior_sessions: Dict[str, list] = {}
    for s in senior_sessions:
        j_name = s['junior_name']
        if j_name not in junior_sessions:
            junior_sessions[j_name] = []
        junior_sessions[j_name].append(s)

    # Update metrics per junior
    for j_name, sessions in junior_sessions.items():
        total_sessions = len(sessions)
        total_duration = sum(s['duration_mins'] for s in sessions)

        MENTORSHIP_SESSIONS_TOTAL.labels(junior_name=j_name, senior_name=senior_name).inc(total_sessions)
        MENTORSHIP_DURATION_MINS_TOTAL.labels(junior_name=j_name, senior_name=senior_name).inc(total_duration)

    # Update junior count and avg duration
    num_juniors = len(junior_sessions)
    MENTORSHIP_JUNIORS_SUPPORTED.labels(senior_name=senior_name).set(num_juniors)

    if senior_sessions:
        avg_duration = sum(s['duration_mins'] for s in senior_sessions) / len(senior_sessions)
        MENTORSHIP_AVG_SESSION_MINS.labels(senior_name=senior_name).set(avg_duration)

def main():
    senior_name = os.getenv('MENTORSHIP_SENIOR_NAME')
    if not senior_name:
        print('Error: MENTORSHIP_SENIOR_NAME environment variable not set', file=sys.stderr)
        sys.exit(1)

    # Start Prometheus HTTP server on port 8000
    try:
        start_http_server(8000)
        print(f'Prometheus metrics server started on port 8000 for senior: {senior_name}')
    except Exception as e:
        print(f'Error starting metrics server: {e}', file=sys.stderr)
        sys.exit(1)

    # Initialize tracker
    tracker = MentorshipTracker()

    # Update metrics every 30 seconds
    while True:
        try:
            update_metrics(tracker, senior_name)
            time.sleep(30)
        except KeyboardInterrupt:
            print('Shutting down metrics exporter')
            break
        except Exception as e:
            print(f'Error updating metrics: {e}', file=sys.stderr)
            time.sleep(30)

if __name__ == '__main__':
    main()

# Example agenda for a mentorship session focused on Go error handling
# 1. Review junior's recent PR #123 (5 mins)
# 2. Walk through Go error wrapping best practices (20 mins)
# 3. Pair program refactoring of utils/parser.go (20 mins)
# 4. Assign action item: Refactor 3 functions in api/handler.go to wrap errors (5 mins)
# 5. Set next session date and topic (5 mins)

# Clone the mentorship kit to customize for your team
git clone https://github.com/oss-senior-dev/mentorship-kit.git
cd mentorship-kit
# Copy the Go error handling template to your team's directory
cp templates/go-error-handling.md ./my-team-templates/
# Edit the template to match your team's coding standards
vim ./my-team-templates/go-error-handling.md

# Generate a 12-month mentorship report for your performance review
python mentorship_tracker.py report --days 365
# Output will look like:
# {
#   "period_days": 365,
#   "total_sessions": 48,
#   "total_duration_mins": 1920,
#   "unique_juniors": 4,
#   "avg_session_mins": 40
# }