Skip to content

first-analysis.md

Latest commit

 

History

History
264 lines (197 loc) · 7.48 KB

first-analysis.md

File metadata and controls

264 lines (197 loc) · 7.48 KB

Your First Analysis

Now that you've completed the Quick Start Tutorial, let's dive deeper into understanding and interpreting GitFlow Analytics output.

🎯 What You'll Learn

This guide will help you:

  • 🔍 Understand each type of report generated
  • 📊 Interpret key metrics and insights
  • 🎨 Customize analysis parameters
  • 🚀 Plan your next analysis steps

📊 Understanding Report Types

GitFlow Analytics generates several complementary report formats:

1. Narrative Report (narrative_report_YYYYMMDD.md)

Purpose: Executive summary with human-readable insights

Key Sections:

  • Executive Summary: High-level metrics and trends
  • Team Composition: Developer profiles and work patterns
  • Project Activity: Breakdown by repository/project
  • Development Patterns: Code quality and collaboration insights
  • Recommendations: Actionable next steps

Example Insights:

## Executive Summary
- **Analysis Period**: July 25 - August 8, 2025 (2 weeks)
- **Total Commits**: 156 commits across 3 repositories
- **Active Developers**: 8 contributors
- **Primary Languages**: Python (45%), TypeScript (30%), Go (25%)

## Team Composition

**John Smith**
- Commits: 42 (26.9% of total)
- Projects: FRONTEND (70.0%), API (30.0%)  
- Work Style: Multi-project contributor
- Focus: Feature development with strong testing patterns

2. CSV Reports

Weekly Metrics (weekly_metrics_YYYYMMDD.csv):

week,commits,unique_authors,files_changed,lines_added,lines_removed
2025-01-27,23,4,67,892,234
2025-02-03,31,5,89,1245,456

Developer Profiles (developers_YYYYMMDD.csv):

developer,commits,percentage,primary_project,secondary_project
John Smith,42,26.9,FRONTEND,API
Jane Doe,38,24.4,API,BACKEND

Summary Statistics (summary_YYYYMMDD.csv):

metric,value
total_commits,156
unique_developers,8
total_files_changed,445
avg_commits_per_week,78

3. Untracked Commits Report

Purpose: Identify work not linked to tickets/issues

Shows commits that don't reference JIRA tickets, GitHub issues, or other trackable work items:

hash,author,date,message,category,files_changed,project
abc123,John Smith,2025-01-28,fix: resolve login bug,bug_fix,3,FRONTEND  
def456,Jane Doe,2025-01-29,docs: update API guide,documentation,1,API

Categories include: feature, bug_fix, refactor, documentation, maintenance, test

🔍 Key Metrics Explained

Developer Metrics

Commit Volume

  • Raw number of commits per developer
  • Percentage of total team activity
  • Note: More commits ≠ better performance

Project Distribution

  • Primary/secondary project assignments
  • Work focus patterns (focused vs. distributed)
  • Cross-project collaboration indicators

Work Patterns

  • Commit timing and frequency
  • File change patterns
  • Collaboration indicators (shared files)

Project Health Indicators

Development Velocity

  • Commits per week trends
  • Lines of code changes
  • File modification patterns

Team Distribution

  • Developer concentration per project
  • Knowledge sharing indicators
  • Bus factor analysis

Code Quality Signals

  • Test-to-code ratios (when detectable)
  • Documentation update patterns
  • Refactoring frequency

🎨 Customizing Your Analysis

Time Periods

analysis:
  # Short-term analysis (good for sprints)
  weeks: 2
  
  # Medium-term analysis (good for quarterly reviews)  
  weeks: 12
  
  # Long-term analysis (good for yearly planning)
  weeks: 52

Focus Areas

analysis:
  # Include ML categorization for better insights
  enable_ml_categorization: true
  
  # Focus on specific file types
  include_file_patterns:
    - "*.py"
    - "*.js"
    - "*.md"
    
  # Exclude generated files
  exclude_file_patterns:
    - "*.min.js"
    - "package-lock.json"

Report Customization

reports:
  # Choose output formats
  formats: ["csv", "json", "markdown"]
  
  # Customize output location
  output_directory: "./reports"
  
  # Include detailed untracked analysis
  include_untracked_analysis: true

💡 Interpreting Common Patterns

High Performer Indicators

  • Consistent commit patterns (not just high volume)
  • Cross-project contributions showing versatility
  • Documentation and test commits indicating quality focus
  • Balanced feature/bug fix ratio

Team Health Signals

  • Even work distribution (no single points of failure)
  • Regular collaboration (shared file modifications)
  • Knowledge sharing patterns (cross-repository commits)
  • Healthy untracked work ratio (10-20% is normal)

Red Flags to Investigate

  • Extreme commit concentration (one person doing 60%+ of work)
  • Zero cross-project collaboration
  • High untracked work percentage (>40% might indicate process issues)
  • Declining velocity trends without obvious causes

🚀 Next Steps Planning

For Team Leads

  1. Review Developer Distribution

    • Are workloads balanced?
    • Who are the knowledge bottlenecks?
    • Where can you improve cross-training?

  2. Assess Project Health

    • Which projects need more attention?
    • Are there resource allocation issues?
    • What's the bus factor for critical projects?

  3. Process Improvements

    • Is untracked work within acceptable ranges?
    • Are developers following ticket tracking processes?
    • Should you adjust development workflows?

For Developers

  1. Personal Insights

    • What's your contribution pattern?
    • Are you focused on one project or distributed?
    • How does your work categorization look?

  2. Career Development

    • Are you contributing to diverse project areas?
    • What's your documentation/testing ratio?
    • How can you increase impact?

  3. Team Collaboration

    • Which teammates do you collaborate with most?
    • Are there opportunities to share knowledge?
    • Can you contribute to different project areas?

🔄 Continuous Analysis

Regular Cadence

  • Weekly: Quick pulse checks during active development
  • Monthly: Detailed team health assessments
  • Quarterly: Strategic planning and trend analysis
  • Yearly: Performance reviews and goal setting

Automation Options

# Set up weekly automated reports
crontab -e
# Add line: 0 9 * * 1 /usr/local/bin/gitflow-analytics -c /path/to/config.yaml

🆘 Common Questions

Q: Why are some of my commits missing? A: Check your time period (weeks setting) and ensure the repository has recent activity within that window.

Q: The developer names look wrong A: Review the identity resolution configuration to consolidate email addresses.

Q: I don't see any untracked commits A: This could mean your team has excellent ticket discipline, or you may need to adjust the untracked_file_threshold setting.

Q: The ML categorization seems inaccurate A: ML models need training data. Check the ML Categorization Guide for tuning options.

🔄 What's Next?

You're now equipped to interpret GitFlow Analytics output! Consider:

Happy analyzing! 📊