|
| 1 | +# kdevops Contribution Analysis |
| 2 | + |
| 3 | +This directory contains contribution visualization tools and generated reports for the kdevops project. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The contribution analysis provides comprehensive insights into kdevops development patterns, contributor activity, and project health over time. These visualizations help understand: |
| 8 | + |
| 9 | +- **Contributor Activity**: Who is actively contributing to the project |
| 10 | +- **Development Patterns**: When and how frequently contributions occur |
| 11 | +- **Project Health**: Overall activity levels and contributor diversity |
| 12 | +- **Timeline Analysis**: How the project has evolved over time |
| 13 | + |
| 14 | +## Quick Start |
| 15 | + |
| 16 | +Generate contribution graphs using the built-in make target: |
| 17 | + |
| 18 | +```bash |
| 19 | +# Generate graphs for a specific year |
| 20 | +make contrib-graph YEAR=2025 |
| 21 | + |
| 22 | +# Generate graphs for all project history |
| 23 | +make contrib-graph |
| 24 | +``` |
| 25 | + |
| 26 | +## Generated Files |
| 27 | + |
| 28 | +The visualization tool creates comprehensive 7-panel dashboards saved as: |
| 29 | + |
| 30 | +### For Specific Year |
| 31 | +- `kdevops_contributions_YYYY.png` - High-resolution image (300 DPI) |
| 32 | +- `kdevops_contributions_YYYY.pdf` - Vector format for scalability |
| 33 | + |
| 34 | +### For All Time |
| 35 | +- `kdevops_contributions_all_time.png` - High-resolution image |
| 36 | +- `kdevops_contributions_all_time.pdf` - Vector format |
| 37 | + |
| 38 | +## Visualization Components |
| 39 | + |
| 40 | +Each generated dashboard includes seven analytical panels: |
| 41 | + |
| 42 | +### 1. Total Commits Bar Chart |
| 43 | +Shows the overall contribution ranking by commit count. Names are automatically shortened for contributors with fewer commits to prevent overlapping labels. |
| 44 | + |
| 45 | +### 2. Contribution Distribution Pie Chart |
| 46 | +Displays the percentage distribution of contributions among top contributors, with smaller contributors grouped as "Others" for clarity. |
| 47 | + |
| 48 | +### 3. Monthly Activity Heatmap |
| 49 | +Visual representation of when contributors are most active throughout the year. Intensity indicates commit volume. |
| 50 | + |
| 51 | +### 4. Monthly Timeline Graph |
| 52 | +Line graph showing total project activity over time, with actual commit counts labeled on data points. |
| 53 | + |
| 54 | +### 5. Top Contributors Timeline |
| 55 | +Individual activity patterns for the top 3 contributors, showing their monthly contribution patterns. |
| 56 | + |
| 57 | +### 6. Statistics Summary |
| 58 | +Key metrics including: |
| 59 | +- Total commits and contributors |
| 60 | +- Average commits per person |
| 61 | +- Most active month |
| 62 | +- Top contributor |
| 63 | +- Analysis period and generation timestamp |
| 64 | +- Generated-by tag usage share |
| 65 | + |
| 66 | +### 7. Generated-by Tag Adoption Trend |
| 67 | +Shows how often commits include the `Generated-by:` trailer each month. This timeline highlights adoption of automated contribution tags and makes it easy to spot growth in AI-assisted commit generation. |
| 68 | + |
| 69 | +## Technical Details |
| 70 | + |
| 71 | +### Date Handling |
| 72 | +- **Smart Filtering**: Only shows data up to the current date (no future commits) |
| 73 | +- **Period Accuracy**: Respects actual time boundaries (e.g., if run on July 31, 2025, won't show August-December data) |
| 74 | +- **Validation**: Prevents analysis of invalid years (too early or future years) |
| 75 | + |
| 76 | +### Data Sources |
| 77 | +All data is extracted directly from the git repository using: |
| 78 | +- `git log` for commit history |
| 79 | +- Author information from git commit metadata |
| 80 | +- Date filtering for accurate time period analysis |
| 81 | +- No synthetic or fabricated data |
| 82 | + |
| 83 | +### Dependencies |
| 84 | +The visualization tool requires: |
| 85 | +- Python 3.x |
| 86 | +- matplotlib |
| 87 | +- seaborn |
| 88 | +- pandas |
| 89 | +- numpy |
| 90 | + |
| 91 | +These are automatically installed via system packages when running the tool. |
| 92 | + |
| 93 | +## Usage Examples |
| 94 | + |
| 95 | +### Annual Review |
| 96 | +```bash |
| 97 | +# Generate 2025 contribution report |
| 98 | +make contrib-graph YEAR=2025 |
| 99 | +``` |
| 100 | + |
| 101 | +### Project History |
| 102 | +```bash |
| 103 | +# Generate complete project history |
| 104 | +make contrib-graph |
| 105 | +``` |
| 106 | + |
| 107 | +### Specific Year Analysis |
| 108 | +```bash |
| 109 | +# Analyze any specific year |
| 110 | +make contrib-graph YEAR=2024 |
| 111 | +make contrib-graph YEAR=2023 |
| 112 | +``` |
| 113 | + |
| 114 | +## Error Handling |
| 115 | + |
| 116 | +The tool includes comprehensive error checking: |
| 117 | + |
| 118 | +- **Future Years**: Prevents analysis of years beyond current date |
| 119 | +- **Invalid Years**: Validates year format and reasonable ranges |
| 120 | +- **Git Repository**: Ensures tool is run from within a git repository |
| 121 | +- **Empty Data**: Handles periods with no commits gracefully |
| 122 | + |
| 123 | +## Integration |
| 124 | + |
| 125 | +The contribution analysis is integrated into the kdevops build system: |
| 126 | + |
| 127 | +- **Makefile Target**: `make contrib-graph` |
| 128 | +- **Parameter Support**: Optional `YEAR=YYYY` parameter |
| 129 | +- **Output Location**: Files saved to `docs/contrib/` |
| 130 | +- **Style Compliance**: Follows kdevops coding standards |
| 131 | + |
| 132 | +## Interpretation Guide |
| 133 | + |
| 134 | +### High Activity Periods |
| 135 | +- **March Surge**: Often indicates major development phases |
| 136 | +- **Consistent Activity**: Shows healthy, sustained development |
| 137 | +- **Seasonal Patterns**: May reflect developer availability/schedules |
| 138 | + |
| 139 | +### Contributor Patterns |
| 140 | +- **Core Contributors**: High commit counts, consistent activity |
| 141 | +- **Occasional Contributors**: Lower counts, sporadic activity |
| 142 | +- **New Contributors**: Recent activity increase |
| 143 | + |
| 144 | +### Project Health Indicators |
| 145 | +- **Growing Contributor Base**: More contributors over time |
| 146 | +- **Sustained Activity**: Regular commits throughout periods |
| 147 | +- **Balanced Contributions**: Activity from multiple contributors |
| 148 | +- **Generated-by Adoption**: Visibility into automated tag usage trends |
| 149 | + |
| 150 | +## Files in This Directory |
| 151 | + |
| 152 | +- `README.md` - This documentation |
| 153 | +- `kdevops_contributions_*.png` - Generated visualization images |
| 154 | +- `kdevops_contributions_*.pdf` - Generated vector graphics |
| 155 | +- Historical contribution reports (accumulate over time) |
| 156 | + |
| 157 | +## Troubleshooting |
| 158 | + |
| 159 | +### Common Issues |
| 160 | + |
| 161 | +**"No contributions found"** |
| 162 | +- Check that you're in a git repository |
| 163 | +- Verify the specified year has commits |
| 164 | +- Ensure date range is valid |
| 165 | + |
| 166 | +**"Year is in the future"** |
| 167 | +- The tool prevents analysis of future dates |
| 168 | +- Use current or past years only |
| 169 | + |
| 170 | +**Missing dependencies** |
| 171 | +- Run `sudo apt install python3-matplotlib python3-seaborn python3-pandas python3-numpy` |
| 172 | +- Or let the Makefile handle dependency installation |
| 173 | + |
| 174 | +### Getting Help |
| 175 | + |
| 176 | +For issues with the contribution analysis tool: |
| 177 | +1. Check that all dependencies are installed |
| 178 | +2. Verify you're in the kdevops git repository root |
| 179 | +3. Review error messages for specific guidance |
| 180 | +4. Consult the main project documentation |
| 181 | + |
| 182 | +## Contributing |
| 183 | + |
| 184 | +The contribution analysis tool itself can be improved: |
| 185 | + |
| 186 | +- **Source**: `scripts/contrib_graph.py` |
| 187 | +- **Integration**: Makefile target definition |
| 188 | +- **Standards**: Follow kdevops coding and documentation standards |
| 189 | +- **Testing**: Verify with multiple years and edge cases |
| 190 | + |
| 191 | +Suggestions for enhancements are welcome through the standard kdevops contribution process. |
0 commit comments