gitflow-analytics 3.8.0__tar.gz → 3.9.2__tar.gz

{gitflow_analytics-3.8.0 → gitflow_analytics-3.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitflow-analytics
-Version: 3.8.0
+Version: 3.9.2
 Summary: Analyze Git repositories for developer productivity insights
 Author-email: Bob Matyas <bobmatnyc@gmail.com>
 License: MIT
@@ -338,13 +338,13 @@ Here's a complete example showing `.env` file and corresponding YAML configurati
 GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
 GITHUB_ORG=your-organization
 
-# JIRA Configuration
+# PM Platform Configuration
 JIRA_ACCESS_USER=developer@company.com
 JIRA_ACCESS_TOKEN=ATATT3xxxxxxxxxxx
+LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
+CLICKUP_API_TOKEN=pk_xxxxxxxxxxxx
 
-# Optional: Other integrations
-# CLICKUP_TOKEN=pk_xxxxxxxxxxxx
-# LINEAR_TOKEN=lin_api_xxxxxxxxxxxx
+# Note: GitHub Issues uses GITHUB_TOKEN automatically
 ```
 
 ### `config.yaml` file
@@ -356,12 +356,22 @@ github:
   token: "${GITHUB_TOKEN}"
   organization: "${GITHUB_ORG}"
 
-# JIRA integration for story points
-jira:
-  access_user: "${JIRA_ACCESS_USER}"
-  access_token: "${JIRA_ACCESS_TOKEN}"
-  base_url: "https://company.atlassian.net"
+# Multi-platform PM integration
+pm:
+  jira:
+    access_user: "${JIRA_ACCESS_USER}"
+    access_token: "${JIRA_ACCESS_TOKEN}"
+    base_url: "https://company.atlassian.net"
 
+  linear:
+    api_key: "${LINEAR_API_KEY}"
+    team_ids: ["team_123abc"]  # Optional: filter by specific teams
+
+  clickup:
+    api_token: "${CLICKUP_API_TOKEN}"
+    workspace_url: "https://app.clickup.com/12345/v/"
+
+# JIRA story point integration (optional)
 jira_integration:
   enabled: true
   fetch_story_points: true
@@ -371,9 +381,12 @@ jira_integration:
 
 # Analysis configuration
 analysis:
-  # Only track JIRA tickets (ignore GitHub issues, etc.)
+  # Track tickets from all configured platforms
   ticket_platforms:
     - jira
+    - linear
+    - clickup
+    - github  # GitHub Issues (uses GITHUB_TOKEN)
   
   # Exclude bot commits and boilerplate files
   exclude:
@@ -666,24 +679,97 @@ story_point_patterns:
 
 ## Ticket Platform Support
 
-Automatically detects and tracks tickets from:
+Automatically detects and tracks tickets from multiple PM platforms:
 - **JIRA**: `PROJ-123`
-- **GitHub**: `#123`, `GH-123`
+- **GitHub Issues**: `#123`, `GH-123`
 - **ClickUp**: `CU-abc123`
 - **Linear**: `ENG-123`
 
-### JIRA Integration
+### Multi-Platform PM Integration
 
-GitFlow Analytics can fetch story points directly from JIRA tickets. Configure your JIRA instance:
+GitFlow Analytics supports multiple project management platforms simultaneously. You can configure one or more platforms based on your team's workflow:
 
 ```yaml
-jira:
-  access_user: "${JIRA_ACCESS_USER}"
-  access_token: "${JIRA_ACCESS_TOKEN}"
-  base_url: "https://your-company.atlassian.net"
+# Configure which platforms to track
+analysis:
+  ticket_platforms:
+    - jira
+    - linear
+    - clickup
+    - github  # GitHub Issues
+
+# Platform-specific configuration
+pm:
+  jira:
+    access_user: "${JIRA_ACCESS_USER}"
+    access_token: "${JIRA_ACCESS_TOKEN}"
+    base_url: "https://your-company.atlassian.net"
+
+  linear:
+    api_key: "${LINEAR_API_KEY}"
+    team_ids:  # Optional: filter by team
+      - "team_123abc"
+
+  clickup:
+    api_token: "${CLICKUP_API_TOKEN}"
+    workspace_url: "https://app.clickup.com/12345/v/"
+
+# GitHub Issues uses existing GitHub token automatically
+github:
+  token: "${GITHUB_TOKEN}"
+```
 
+### Platform Setup Guides
+
+#### JIRA Setup
+1. **Get API Token**: Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. **Required Permissions**: Read access to projects and issues
+3. **Configuration**:
+   ```yaml
+   pm:
+     jira:
+       access_user: "${JIRA_ACCESS_USER}"  # Your Atlassian email
+       access_token: "${JIRA_ACCESS_TOKEN}"
+       base_url: "https://your-company.atlassian.net"
+   ```
+
+#### Linear Setup
+1. **Get API Key**: Go to [Linear Settings → API](https://linear.app/settings/api)
+2. **Required Permissions**: Read access to issues
+3. **Configuration**:
+   ```yaml
+   pm:
+     linear:
+       api_key: "${LINEAR_API_KEY}"
+       team_ids: ["team_123abc"]  # Optional: specify team IDs
+   ```
+
+#### ClickUp Setup
+1. **Get API Token**: Go to [ClickUp Settings → Apps](https://app.clickup.com/settings/apps)
+2. **Get Workspace URL**: Copy from browser when viewing your workspace
+3. **Configuration**:
+   ```yaml
+   pm:
+     clickup:
+       api_token: "${CLICKUP_API_TOKEN}"
+       workspace_url: "https://app.clickup.com/12345/v/"
+   ```
+
+#### GitHub Issues Setup
+GitHub Issues is automatically enabled when GitHub integration is configured. No additional setup required:
+```yaml
+github:
+  token: "${GITHUB_TOKEN}"  # Same token for repo access and issues
+```
+
+### JIRA Story Point Integration
+
+GitFlow Analytics can fetch story points directly from JIRA tickets:
+
+```yaml
 jira_integration:
   enabled: true
+  fetch_story_points: true
   story_point_fields:
     - "Story point estimate"  # Your custom field name
     - "customfield_10016"     # Or use field ID
@@ -694,6 +780,21 @@ To discover your JIRA story point fields:
 gitflow-analytics discover-storypoint-fields -c config.yaml
 ```
 
+### Environment Variables for Credentials
+
+Store credentials securely in a `.env` file:
+
+```bash
+# .env file (keep this secure and don't commit to git!)
+GITHUB_TOKEN=ghp_your_token_here
+
+# PM Platform Credentials
+JIRA_ACCESS_USER=your.email@company.com
+JIRA_ACCESS_TOKEN=ATATT3xxxxxxxxxxx
+LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
+CLICKUP_API_TOKEN=pk_xxxxxxxxxxxx
+```
+
 ## Caching
 
 The tool uses SQLite for intelligent caching:

{gitflow_analytics-3.8.0 → gitflow_analytics-3.9.2}/README.md

@@ -280,13 +280,13 @@ Here's a complete example showing `.env` file and corresponding YAML configurati
 GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
 GITHUB_ORG=your-organization
 
-# JIRA Configuration
+# PM Platform Configuration
 JIRA_ACCESS_USER=developer@company.com
 JIRA_ACCESS_TOKEN=ATATT3xxxxxxxxxxx
+LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
+CLICKUP_API_TOKEN=pk_xxxxxxxxxxxx
 
-# Optional: Other integrations
-# CLICKUP_TOKEN=pk_xxxxxxxxxxxx
-# LINEAR_TOKEN=lin_api_xxxxxxxxxxxx
+# Note: GitHub Issues uses GITHUB_TOKEN automatically
 ```
 
 ### `config.yaml` file
@@ -298,12 +298,22 @@ github:
   token: "${GITHUB_TOKEN}"
   organization: "${GITHUB_ORG}"
 
-# JIRA integration for story points
-jira:
-  access_user: "${JIRA_ACCESS_USER}"
-  access_token: "${JIRA_ACCESS_TOKEN}"
-  base_url: "https://company.atlassian.net"
+# Multi-platform PM integration
+pm:
+  jira:
+    access_user: "${JIRA_ACCESS_USER}"
+    access_token: "${JIRA_ACCESS_TOKEN}"
+    base_url: "https://company.atlassian.net"
 
+  linear:
+    api_key: "${LINEAR_API_KEY}"
+    team_ids: ["team_123abc"]  # Optional: filter by specific teams
+
+  clickup:
+    api_token: "${CLICKUP_API_TOKEN}"
+    workspace_url: "https://app.clickup.com/12345/v/"
+
+# JIRA story point integration (optional)
 jira_integration:
   enabled: true
   fetch_story_points: true
@@ -313,9 +323,12 @@ jira_integration:
 
 # Analysis configuration
 analysis:
-  # Only track JIRA tickets (ignore GitHub issues, etc.)
+  # Track tickets from all configured platforms
   ticket_platforms:
     - jira
+    - linear
+    - clickup
+    - github  # GitHub Issues (uses GITHUB_TOKEN)
   
   # Exclude bot commits and boilerplate files
   exclude:
@@ -608,24 +621,97 @@ story_point_patterns:
 
 ## Ticket Platform Support
 
-Automatically detects and tracks tickets from:
+Automatically detects and tracks tickets from multiple PM platforms:
 - **JIRA**: `PROJ-123`
-- **GitHub**: `#123`, `GH-123`
+- **GitHub Issues**: `#123`, `GH-123`
 - **ClickUp**: `CU-abc123`
 - **Linear**: `ENG-123`
 
-### JIRA Integration
+### Multi-Platform PM Integration
 
-GitFlow Analytics can fetch story points directly from JIRA tickets. Configure your JIRA instance:
+GitFlow Analytics supports multiple project management platforms simultaneously. You can configure one or more platforms based on your team's workflow:
 
 ```yaml
-jira:
-  access_user: "${JIRA_ACCESS_USER}"
-  access_token: "${JIRA_ACCESS_TOKEN}"
-  base_url: "https://your-company.atlassian.net"
+# Configure which platforms to track
+analysis:
+  ticket_platforms:
+    - jira
+    - linear
+    - clickup
+    - github  # GitHub Issues
+
+# Platform-specific configuration
+pm:
+  jira:
+    access_user: "${JIRA_ACCESS_USER}"
+    access_token: "${JIRA_ACCESS_TOKEN}"
+    base_url: "https://your-company.atlassian.net"
+
+  linear:
+    api_key: "${LINEAR_API_KEY}"
+    team_ids:  # Optional: filter by team
+      - "team_123abc"
+
+  clickup:
+    api_token: "${CLICKUP_API_TOKEN}"
+    workspace_url: "https://app.clickup.com/12345/v/"
+
+# GitHub Issues uses existing GitHub token automatically
+github:
+  token: "${GITHUB_TOKEN}"
+```
 
+### Platform Setup Guides
+
+#### JIRA Setup
+1. **Get API Token**: Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. **Required Permissions**: Read access to projects and issues
+3. **Configuration**:
+   ```yaml
+   pm:
+     jira:
+       access_user: "${JIRA_ACCESS_USER}"  # Your Atlassian email
+       access_token: "${JIRA_ACCESS_TOKEN}"
+       base_url: "https://your-company.atlassian.net"
+   ```
+
+#### Linear Setup
+1. **Get API Key**: Go to [Linear Settings → API](https://linear.app/settings/api)
+2. **Required Permissions**: Read access to issues
+3. **Configuration**:
+   ```yaml
+   pm:
+     linear:
+       api_key: "${LINEAR_API_KEY}"
+       team_ids: ["team_123abc"]  # Optional: specify team IDs
+   ```
+
+#### ClickUp Setup
+1. **Get API Token**: Go to [ClickUp Settings → Apps](https://app.clickup.com/settings/apps)
+2. **Get Workspace URL**: Copy from browser when viewing your workspace
+3. **Configuration**:
+   ```yaml
+   pm:
+     clickup:
+       api_token: "${CLICKUP_API_TOKEN}"
+       workspace_url: "https://app.clickup.com/12345/v/"
+   ```
+
+#### GitHub Issues Setup
+GitHub Issues is automatically enabled when GitHub integration is configured. No additional setup required:
+```yaml
+github:
+  token: "${GITHUB_TOKEN}"  # Same token for repo access and issues
+```
+
+### JIRA Story Point Integration
+
+GitFlow Analytics can fetch story points directly from JIRA tickets:
+
+```yaml
 jira_integration:
   enabled: true
+  fetch_story_points: true
   story_point_fields:
     - "Story point estimate"  # Your custom field name
     - "customfield_10016"     # Or use field ID
@@ -636,6 +722,21 @@ To discover your JIRA story point fields:
 gitflow-analytics discover-storypoint-fields -c config.yaml
 ```
 
+### Environment Variables for Credentials
+
+Store credentials securely in a `.env` file:
+
+```bash
+# .env file (keep this secure and don't commit to git!)
+GITHUB_TOKEN=ghp_your_token_here
+
+# PM Platform Credentials
+JIRA_ACCESS_USER=your.email@company.com
+JIRA_ACCESS_TOKEN=ATATT3xxxxxxxxxxx
+LINEAR_API_KEY=lin_api_xxxxxxxxxxxx
+CLICKUP_API_TOKEN=pk_xxxxxxxxxxxx
+```
+
 ## Caching
 
 The tool uses SQLite for intelligent caching:

{gitflow_analytics-3.8.0 → gitflow_analytics-3.9.2}/docs/configuration/configuration.md

@@ -98,6 +98,50 @@ reports:
   anonymize: false                      # Anonymize developer names
 ```
 
+### PM Platform Configuration
+
+GitFlow Analytics supports multiple project management platforms for ticket tracking:
+
+```yaml
+# Configure which platforms to track
+analysis:
+  ticket_platforms:
+    - jira        # Track JIRA tickets (PROJ-123)
+    - linear      # Track Linear issues (ENG-123)
+    - clickup     # Track ClickUp tasks (CU-abc123)
+    - github      # Track GitHub Issues (#123, GH-123)
+
+# Platform-specific configuration
+pm:
+  jira:
+    access_user: "${JIRA_ACCESS_USER}"
+    access_token: "${JIRA_ACCESS_TOKEN}"
+    base_url: "https://company.atlassian.net"
+
+  linear:
+    api_key: "${LINEAR_API_KEY}"
+    team_ids:  # Optional: filter by team
+      - "team_123abc"
+
+  clickup:
+    api_token: "${CLICKUP_API_TOKEN}"
+    workspace_url: "https://app.clickup.com/12345/v/"
+
+# GitHub Issues uses github.token automatically - no separate config needed
+github:
+  token: "${GITHUB_TOKEN}"
+
+# Optional: JIRA story point integration
+jira_integration:
+  enabled: true
+  fetch_story_points: true
+  story_point_fields:
+    - "Story point estimate"
+    - "customfield_10016"
+```
+
+See the [PM Platform Setup Guide](../guides/pm-platform-setup.md) for detailed setup instructions for each platform.
+
 ## Configuration Profiles
 
 Configuration profiles provide pre-configured settings optimized for specific use cases. This allows you to quickly set up GitFlow Analytics for different scenarios without manually configuring every setting.
@@ -317,9 +361,27 @@ For teams, create a shared base configuration:
 version: "1.0"
 github:
   organization: "our-company"
+
+# Multi-platform PM configuration
+pm:
+  jira:
+    access_user: "${JIRA_ACCESS_USER}"
+    access_token: "${JIRA_ACCESS_TOKEN}"
+    base_url: "https://company.atlassian.net"
+
+  linear:
+    api_key: "${LINEAR_API_KEY}"
+    team_ids: ["team_123"]
+
 analysis:
+  ticket_platforms:
+    - jira
+    - linear
+    - github
+
   exclude:
     authors: ["bot-accounts"]
+
   identity:
     manual_mappings:
       - name: "John Smith"

{gitflow_analytics-3.8.0 → gitflow_analytics-3.9.2}/docs/getting-started/installation.md

@@ -68,7 +68,7 @@ GitFlow Analytics will automatically install required dependencies:
    ```bash
    # Option 1: Set in your shell profile (.bashrc, .zshrc, etc.)
    export GITHUB_TOKEN="ghp_your_token_here"
-   
+
    # Option 2: Create a .env file (recommended)
    echo "GITHUB_TOKEN=ghp_your_token_here" > .env
    ```
@@ -79,6 +79,24 @@ GitFlow Analytics will automatically install required dependencies:
    curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user
    ```
 
+### PM Platform Setup (Optional)
+
+GitFlow Analytics supports multiple project management platforms for enhanced ticket tracking:
+
+- **JIRA** - Enterprise project management
+- **Linear** - Modern issue tracking
+- **ClickUp** - All-in-one productivity
+- **GitHub Issues** - Native GitHub integration (auto-configured with GitHub token)
+
+**Quick Setup**: Use the interactive launcher:
+```bash
+gitflow-analytics launcher
+```
+
+Select **Profile 1 (Standard)** and choose which PM platforms to configure.
+
+**Manual Setup**: See the [PM Platform Setup Guide](../guides/pm-platform-setup.md) for detailed instructions on obtaining and configuring credentials for each platform.
+
 ## 🧪 Verify Installation
 
 ### Basic Verification

{gitflow_analytics-3.8.0 → gitflow_analytics-3.9.2}/docs/guides/README.md

@@ -12,11 +12,20 @@ Master the YAML configuration format with detailed examples covering:
 - Advanced analysis options and filters
 - Report customization and output formats
 
-### [ML Categorization Setup](ml-categorization.md)  
+### [PM Platform Setup](pm-platform-setup.md)
+Configure multiple project management platforms for ticket tracking:
+- **JIRA** - Enterprise project management integration
+- **Linear** - Modern issue tracking setup
+- **ClickUp** - All-in-one productivity platform
+- **GitHub Issues** - Native GitHub integration
+- Multi-platform configuration and credential management
+- Story point extraction and ticket coverage analysis
+
+### [ML Categorization Setup](ml-categorization.md)
 Enable machine learning features for intelligent commit classification:
 - Install and configure spaCy language models
 - Set up ML-powered commit categorization (85-95% accuracy)
-- Customize classification categories and thresholds  
+- Customize classification categories and thresholds
 - Monitor and improve model performance
 
 ### [Organization-Wide Setup](organization-setup.md)
@@ -59,9 +68,12 @@ Solutions to common issues and problems:
 **Analyze a single repository**
 → [Configuration Guide](configuration.md) → [Repository Setup Section](configuration.md#repository-configuration)
 
-**Analyze my entire organization**  
+**Analyze my entire organization**
 → [Organization Setup](organization-setup.md) → [Organization Discovery](organization-setup.md#automatic-discovery)
 
+**Track tickets from JIRA, Linear, or ClickUp**
+→ [PM Platform Setup](pm-platform-setup.md) → [Platform Configuration](pm-platform-setup.md#platform-configuration)
+
 **Get better commit categorization**
 → [ML Categorization](ml-categorization.md) → [Model Setup](ml-categorization.md#installation)
 
@@ -71,7 +83,7 @@ Solutions to common issues and problems:
 **Fix configuration issues**
 → [Troubleshooting](troubleshooting.md) → [Configuration Errors](troubleshooting.md#configuration-issues)
 
-**Add AI insights**  
+**Add AI insights**
 → [ChatGPT Setup](chatgpt-setup.md) → [API Configuration](chatgpt-setup.md#setup)
 
 **Solve authentication problems**
@@ -82,7 +94,7 @@ Solutions to common issues and problems:
 
 ## 📚 Guide Difficulty Levels
 
-- 🟢 **Beginner**: Configuration Guide, Troubleshooting
+- 🟢 **Beginner**: Configuration Guide, PM Platform Setup, Troubleshooting
 - 🟡 **Intermediate**: Organization Setup, Report Customization
 - 🔴 **Advanced**: ML Categorization, ChatGPT Integration