# plone-contributor-statistics

**Repository Path**: mirrors_plone/plone-contributor-statistics

## Basic Information

- **Project Name**: plone-contributor-statistics
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-22
- **Last Updated**: 2026-05-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Plone Contributor Statistics Extractor

Comprehensive GitHub statistics extraction and analysis system for the Plone ecosystem, including individual contributor stats, organisation attribution, and PLIP (Plone Improvement Proposals) tracking across all Plone repositories.

## Features

- **Complete Repository Coverage**: Processes all 300+ repositories in the Plone organization
- **Multi-Year Analysis**: Historical data extraction from 2005-2025
- **Volto Statistics**: Dedicated contributor statistics for the plone/volto repository
- **Organisation Mapping**: Attribution system mapping 109+ contributors to 54+ organisations
- **PLIP Tracking**: Extract and analyze Plone Improvement Proposals across repositories
- **Cross-Year Analysis**: Identify Independent contributors for organisation mapping
- **GitHub API Integration**: Handles authentication, rate limiting, and pagination
- **Automated Workflows**: Makefile commands for all analysis tasks

## Quick Start

```bash
# Setup environment and dependencies
make setup

# Run current year (2025) statistics
make run-stats

# Run statistics for individual years (e.g. 2022)
make run-stats-2022

# Run organisation statistics (this requires <YEAR>-plone-contributors.csv files to be present)
make run-organisation-stats

# Generate yearly graphs
make yearly-graphs

# Generate Flourish Graphs
make flourish-graph-individual-contributors-csv-file
make flourish-graph-organisation-contributors-csv-file

# Extract PLIP statistics
make run-plips

# Show all available commands
make help
```

## Main Makefile Commands

### Individual Contributor Statistics

```bash
# Current year (2025)
make run-stats

# Specific years (2005-2025 available)
make run-stats-2024
make run-stats-2023
make run-stats-2022
# ... (all years 2005-2025)

# Custom date range
python plone_contributors.py --start-date 2024-01-01 --end-date 2024-06-30
```

### Organisation Statistics

```bash
# Current year organisation stats
make run-organisation-stats

# Specific years (2005-2025 available)
make run-organisation-stats-2024
make run-organisation-stats-2023
make run-organisation-stats-2022
# ... (all years 2005-2025)
```

### Volto Statistics

Extract contributor statistics from the plone/volto repository:

```bash
# Current year (defaults to 2025)
make run-volto-stats

# Specific years (2005-2025 available)
make run-volto-stats-2024
make run-volto-stats-2023
make run-volto-stats-2022
# ... (all years 2005-2025)

# Generate Volto report
make generate-volto-report
```

### PLIP (Plone Improvement Proposals) Analysis

```bash
# Extract PLIP statistics from all repositories
make run-plips

# Generate PLIP organisation statistics
make run-plip-organisations
```

### Analysis and Maintenance

```bash
# Analyze Independent contributors for organisation mapping
make analyze-independent

# Clean generated files
make clean

# Code quality checks
make lint
make format
make check
```

## Generated Files

### Individual Statistics

- `data/YYYY-plone-contributors.csv` - Individual contributor stats by year
- Raw data with commits, PRs, repositories, and date ranges per contributor

### Organisation Statistics

- `data/YYYY-plone-organisation-contributors.csv` - Organisation-aggregated stats
- Shows total activity by organisation with contributor attribution

### Volto Statistics

- `data/YYYY-volto-stats.csv` - Volto contributor statistics by year
- Contains: `github_username`, `pull_requests`, `commits`
- Sorted by pull requests (descending)
- Report: `reports/volto.md`

### PLIP Statistics

- `plone-plips.csv` - PLIP counts per author (aggregated)
- `plone-plips-detailed.csv` - Individual PLIP records
- `plone-plip-organisations.csv` - PLIP statistics by organisation

### Flourish Charts

- Individual Contributors: https://public.flourish.studio/visualisation/24775871/
- Organisations: https://public.flourish.studio/visualisation/24775561/

### Configuration

- `organisations.csv` - Maps contributors to organisations
- Columns: `Organisation`, `Team` (semicolon-separated GitHub usernames)

## Key Features

### Organisation Mapping System

The system maps 109+ contributors across 54+ organisations including:

- **kitconcept**: Leading contributor with comprehensive Plone development
- **nuclia**: Significant PLIP contributions and core development
- **syslab**: Multi-year contributor across various repositories
- **Independent**: Unmapped individual contributors

### PLIP Tracking

Extracts PLIPs from three main repositories:

- **Products.CMFPlone**: Core Plone functionality (227 PLIPs)
- **volto**: Modern frontend (75 PLIPs)
- **plone.restapi**: REST API (6 PLIPs)

### Cross-Year Analysis

- Track contributor activity patterns across years
- Identify Independent contributors for potential organisation mapping
- Generate comprehensive statistics from 2005-2025

## Setup

1. **Install dependencies**:

```bash
make install
# or manually: pip install requests pandas python-dotenv
```

2. **GitHub Token Setup**:

```bash
make setup
# Edit .env file with your GitHub token
```

3. **Development Setup** (optional):

```bash
make dev-setup  # Includes linting and formatting tools
```

## Usage Examples

### Complete Analysis Workflow

```bash
# 1. Extract individual stats for 2024
make run-stats-2024

# 2. Generate organisation stats for 2024
make run-organisation-stats-2024

# 3. Analyze remaining Independent contributors
make analyze-independent

# 4. Extract PLIP statistics
make run-plips

# 5. Generate PLIP organisation statistics
make run-plip-organisations
```

### Multi-Year Organisation Analysis

```bash
# Generate organisation stats for multiple years
make run-organisation-stats-2024
make run-organisation-stats-2023
make run-organisation-stats-2022
```

## Data Analysis Results

### Top Organisations by Activity (2024 example)

- **kitconcept**: ~2,000+ commits across 100+ repositories
- **nuclia**: Major PLIP contributor with 37 proposals
- **syslab**: Consistent multi-repository contributor
- **py76**: High-volume individual contributor

### PLIP Statistics

- **Total PLIPs**: 317 (71 open, 237 closed)
- **Top PLIP Authors**: tisto (60), sneridagh (32), bloodbare (20)
- **Repository Distribution**: Products.CMFPlone (73%), volto (24%), plone.restapi (2%)

## GitHub API Considerations

- **With token**: 5,000 requests per hour
- **Without token**: 60 requests per hour (not recommended)
- Built-in rate limiting and retry logic
- Handles pagination for large datasets

## Data Collection Methodology

### Pull Request Counting

All contributor statistics count only **merged** pull requests.
The counts exclude the following pull request statuses.
- Open pull requests (still under review)
- Closed but not merged pull requests (rejected)

This ensures statistics reflect actual contributions to the codebase.

**Exception**: PR interaction statistics (`plone_pr_interactions.py`) count all interactions (comments, reviews) on any PR, regardless of merge status, to accurately capture community engagement.

### Commit Counting

Commits are counted from the default branch only, which automatically includes:
- Direct commits to the default branch
- Commits from merged pull requests

This excludes commits on unmerged branches or rejected pull requests.