gitflow-analytics 3.13.0__py3-none-any.whl → 3.13.6__py3-none-any.whl

gitflow_analytics/cli_wizards/menu.py

@@ -5,6 +5,7 @@ is run without arguments, offering options for configuration, alias management,
 analysis execution, and more.
 """
 
+import contextlib
 import logging
 import os
 import subprocess
@@ -98,10 +99,8 @@ def _atomic_yaml_write(config_path: Path, config_data: dict) -> None:
     except Exception as e:
         # Cleanup temp file on error
         if temp_fd is not None:
-            try:
+            with contextlib.suppress(Exception):
                 os.close(temp_fd)
-            except Exception:
-                pass
 
         if temp_path and temp_path.exists():
             temp_path.unlink(missing_ok=True)
@@ -242,7 +241,7 @@ def validate_config(config_path: Path) -> bool:
 
                     # Line before
                     if mark.line > 0:
-                        click.echo(f"   {mark.line}: {lines[mark.line-1].rstrip()}", err=True)
+                        click.echo(f"   {mark.line}: {lines[mark.line - 1].rstrip()}", err=True)
 
                     # Problematic line (highlighted)
                     click.echo(
@@ -256,7 +255,7 @@ def validate_config(config_path: Path) -> bool:
 
                     # Line after
                     if mark.line + 1 < len(lines):
-                        click.echo(f"   {mark.line + 2}: {lines[mark.line+1].rstrip()}", err=True)
+                        click.echo(f"   {mark.line + 2}: {lines[mark.line + 1].rstrip()}", err=True)
             except Exception:
                 # If we can't read file, just skip context
                 pass
@@ -562,6 +561,145 @@ def run_full_analysis(config_path: Path) -> bool:
     return success
 
 
+def rename_developer_alias(config_path: Path) -> bool:
+    """Interactive interface for renaming developer aliases.
+
+    Args:
+        config_path: Path to config.yaml file
+
+    Returns:
+        True if rename succeeded, False otherwise.
+    """
+    click.echo("\n" + "=" * 60)
+    click.echo(click.style("Rename Developer Alias", fg="cyan", bold=True))
+    click.echo("=" * 60 + "\n")
+
+    click.echo("Update a developer's canonical display name in reports.")
+    click.echo("This updates the configuration file and optionally the cache.\n")
+
+    try:
+        # Load config to get manual_mappings
+        with open(config_path) as f:
+            config_data = yaml.safe_load(f)
+
+        # Navigate to manual_mappings
+        manual_mappings = (
+            config_data.get("analysis", {}).get("identity", {}).get("manual_mappings", [])
+        )
+
+        if not manual_mappings:
+            click.echo(
+                click.style(
+                    "❌ No manual_mappings found in config. Please add developers first.", fg="red"
+                ),
+                err=True,
+            )
+            return False
+
+        # Display numbered list of developers
+        click.echo(click.style("Current Developers:", fg="cyan", bold=True))
+        click.echo()
+
+        developer_names = []
+        for idx, mapping in enumerate(manual_mappings, 1):
+            name = mapping.get("name", "Unknown")
+            email = mapping.get("primary_email", "N/A")
+            alias_count = len(mapping.get("aliases", []))
+
+            developer_names.append(name)
+            click.echo(f"  {idx}. {click.style(name, fg='green')}")
+            click.echo(f"     Email: {email}")
+            click.echo(f"     Aliases: {alias_count} email(s)")
+            click.echo()
+
+        # Prompt for selection
+        try:
+            selection = click.prompt(
+                "Select developer number to rename (or 0 to cancel)",
+                type=click.IntRange(0, len(developer_names)),
+            )
+        except click.Abort:
+            click.echo(click.style("\n❌ Cancelled", fg="yellow"))
+            return False
+
+        if selection == 0:
+            click.echo(click.style("\n❌ Cancelled", fg="yellow"))
+            return False
+
+        # Get selected developer name
+        old_name = developer_names[selection - 1]
+        click.echo(f"\n📝 Selected: {click.style(old_name, fg='green')}")
+
+        # Prompt for new name
+        new_name = click.prompt("Enter new canonical name", type=str)
+
+        # Validate new name
+        new_name = new_name.strip()
+        if not new_name:
+            click.echo(click.style("❌ New name cannot be empty", fg="red"), err=True)
+            return False
+
+        if new_name == old_name:
+            click.echo(click.style("❌ New name is identical to current name", fg="yellow"))
+            return False
+
+        # Ask about cache update
+        update_cache = click.confirm("\nAlso update database cache?", default=True)
+
+        # Show what will be done
+        click.echo("\n" + "=" * 60)
+        click.echo(click.style("Summary", fg="yellow", bold=True))
+        click.echo("=" * 60)
+        click.echo(f"  Old name: {old_name}")
+        click.echo(f"  New name: {new_name}")
+        click.echo(f"  Update cache: {'Yes' if update_cache else 'No'}")
+        click.echo()
+
+        # Confirm
+        if not click.confirm("Proceed with rename?", default=True):
+            click.echo(click.style("\n❌ Cancelled", fg="yellow"))
+            return False
+
+    except Exception as e:
+        click.echo(click.style(f"❌ Error reading config: {e}", fg="red"), err=True)
+        logger.error(f"Config read error: {type(e).__name__}: {e}")
+        return False
+
+    try:
+        # Validate config path
+        _validate_subprocess_path(config_path)
+    except ValueError as e:
+        click.echo(click.style(f"❌ Invalid config path: {e}", fg="red"), err=True)
+        logger.error(f"Config path validation failed: {e}")
+        return False
+
+    # Build command
+    cmd = [
+        sys.executable,
+        "-m",
+        "gitflow_analytics.cli",
+        "alias-rename",
+        "-c",
+        str(config_path),
+        "--old-name",
+        old_name,
+        "--new-name",
+        new_name,
+    ]
+
+    if update_cache:
+        cmd.append("--update-cache")
+
+    # Run with timeout
+    success = _run_subprocess_safely(cmd, operation_name="Alias Rename", timeout=60)
+
+    if success:
+        click.echo(click.style("\n✅ Rename completed successfully!", fg="green"))
+        click.echo(f"Future reports will show '{new_name}' instead of '{old_name}'")
+
+    return success
+
+
 def show_main_menu(config_path: Optional[Path] = None) -> None:
     """Display main interactive menu.
 
@@ -597,13 +735,14 @@ def show_main_menu(config_path: Optional[Path] = None) -> None:
             click.echo("  3. Re-pull Data (Re-run Analysis)")
             click.echo("  4. Set Number of Weeks")
             click.echo("  5. Run Full Analysis")
+            click.echo("  6. Rename Developer Alias")
             click.echo("  0. Exit")
 
             # Get user choice
             click.echo()
             choice = click.prompt(
                 click.style("Enter your choice", fg="yellow"),
-                type=click.Choice(["0", "1", "2", "3", "4", "5"], case_sensitive=False),
+                type=click.Choice(["0", "1", "2", "3", "4", "5", "6"], case_sensitive=False),
                 show_choices=False,
             )
 
@@ -623,6 +762,8 @@ def show_main_menu(config_path: Optional[Path] = None) -> None:
                 success = set_weeks(config_path)
             elif choice == "5":
                 success = run_full_analysis(config_path)
+            elif choice == "6":
+                success = rename_developer_alias(config_path)
 
             # Show warning if operation failed
             if not success and choice != "0":

gitflow_analytics/config/loader.py

@@ -968,7 +968,9 @@ class ConfigLoader:
                     (
                         cls._resolve_env_var(item)
                         if isinstance(item, str)
-                        else cls._resolve_config_dict(item) if isinstance(item, dict) else item
+                        else cls._resolve_config_dict(item)
+                        if isinstance(item, dict)
+                        else item
                     )
                     for item in value
                 ]

gitflow_analytics/config/profiles.py

@@ -234,8 +234,7 @@ class ProfileManager:
         if not profile_class:
             available = ", ".join(cls._profiles.keys())
             raise ValueError(
-                f"Unknown configuration profile: {profile_name}. "
-                f"Available profiles: {available}"
+                f"Unknown configuration profile: {profile_name}. Available profiles: {available}"
             )
 
         profile_settings = profile_class.get_settings()

gitflow_analytics/core/data_fetcher.py

@@ -192,7 +192,6 @@ class GitDataFetcher:
             description=f"📊 Processing repository: {project_key}",
             unit="steps",
         ) as repo_progress_ctx:
-
             # Step 1: Fetch commits
             progress.set_description(repo_progress_ctx, f"🔍 {project_key}: Fetching commits")
             daily_commits = self._fetch_commits_by_day(
@@ -538,7 +537,6 @@ class GitDataFetcher:
             unit="days",
             nested=True,
         ) as day_progress_ctx:
-
             for day_date in days_to_process:
                 # Update description to show current repository and day clearly
                 day_str = day_date.strftime("%Y-%m-%d")

gitflow_analytics/core/git_auth.py

@@ -112,6 +112,80 @@ def setup_git_credentials(token: str, username: str = "git") -> bool:
         return False
 
 
+def ensure_remote_url_has_token(repo_path: Path, token: str) -> bool:
+    """Embed GitHub token in remote URL for HTTPS authentication.
+
+    This is needed because subprocess git operations may not have access
+    to the credential helper store due to environment variable restrictions
+    (GIT_CREDENTIAL_HELPER="" and GIT_ASKPASS="/bin/echo" in git_timeout_wrapper).
+
+    Args:
+        repo_path: Path to the git repository
+        token: GitHub personal access token
+
+    Returns:
+        True if URL was updated with token, False if already has token,
+        not applicable (SSH URL), or operation failed
+    """
+    if not token:
+        logger.debug("No token provided, skipping remote URL update")
+        return False
+
+    try:
+        # Get current origin remote URL
+        result = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            cwd=repo_path,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        current_url = result.stdout.strip()
+
+        if not current_url:
+            logger.debug(f"No origin remote found for {repo_path}")
+            return False
+
+        # Check if it's an HTTPS GitHub URL without embedded token
+        if current_url.startswith("https://github.com/"):
+            # URL format: https://github.com/org/repo.git
+            # New format: https://git:TOKEN@github.com/org/repo.git
+            new_url = current_url.replace("https://github.com/", f"https://git:{token}@github.com/")
+
+            # Update the remote URL
+            subprocess.run(
+                ["git", "remote", "set-url", "origin", new_url],
+                cwd=repo_path,
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            logger.debug(f"Updated remote URL with embedded token for {repo_path.name}")
+            return True
+
+        elif "@github.com" in current_url:
+            # Already has authentication embedded (either token or SSH)
+            logger.debug(f"Remote URL already has authentication for {repo_path.name}")
+            return False
+
+        elif current_url.startswith("git@github.com:"):
+            # SSH URL, no need to modify
+            logger.debug(f"Using SSH authentication for {repo_path.name}")
+            return False
+
+        else:
+            # Unknown URL format
+            logger.debug(f"Unknown URL format for {repo_path.name}: {current_url}")
+            return False
+
+    except subprocess.CalledProcessError as e:
+        logger.warning(f"Could not update remote URL for {repo_path.name}: {e.stderr}")
+        return False
+    except Exception as e:
+        logger.warning(f"Unexpected error updating remote URL for {repo_path.name}: {e}")
+        return False
+
+
 def preflight_git_authentication(config: dict) -> bool:
     """Run pre-flight checks for git authentication and setup credentials.
 

gitflow_analytics/core/git_timeout_wrapper.py

@@ -14,6 +14,7 @@ from pathlib import Path
 from typing import Callable, Optional, TypeVar
 
 from ..constants import Timeouts
+from .git_auth import ensure_remote_url_has_token
 
 logger = logging.getLogger(__name__)
 
@@ -208,6 +209,13 @@ class GitTimeoutWrapper:
             True if fetch succeeded, False otherwise
         """
         try:
+            # Embed GitHub token in remote URL if available
+            # This is necessary because git operations run with GIT_CREDENTIAL_HELPER=""
+            # and GIT_ASKPASS="/bin/echo", which disable credential helpers
+            token = os.environ.get("GITHUB_TOKEN")
+            if token:
+                ensure_remote_url_has_token(repo_path, token)
+
             self.run_git_command(
                 ["git", "fetch", "--all"], cwd=repo_path, timeout=timeout, check=True
             )

gitflow_analytics/extractors/tickets.py

@@ -503,7 +503,9 @@ class TicketExtractor:
                             :100
                         ],  # Increased from 60 to 100
                         "full_message": commit.get("message", ""),
-                        "author": commit.get("canonical_name", commit.get("author_name", "Unknown")),
+                        "author": commit.get(
+                            "canonical_name", commit.get("author_name", "Unknown")
+                        ),
                         "author_email": commit.get("author_email", ""),
                         "canonical_id": commit.get("canonical_id", commit.get("author_email", "")),
                         "timestamp": commit.get("timestamp"),

gitflow_analytics/integrations/github_integration.py

@@ -101,7 +101,7 @@ class GitHubIntegration:
 
         if cache_hits > 0 or cache_misses > 0:
             print(
-                f"   📊 GitHub PR cache: {cache_hits} hits, {cache_misses} misses ({cache_hits/(cache_hits+cache_misses)*100:.1f}% hit rate)"
+                f"   📊 GitHub PR cache: {cache_hits} hits, {cache_misses} misses ({cache_hits / (cache_hits + cache_misses) * 100:.1f}% hit rate)"
                 if (cache_hits + cache_misses) > 0
                 else ""
             )

gitflow_analytics/integrations/jira_integration.py

@@ -186,7 +186,7 @@ class JIRAIntegration:
 
         if cache_hits > 0 or cache_misses > 0:
             print(
-                f"   📊 JIRA cache: {cache_hits} hits, {cache_misses} misses ({cache_hits/(cache_hits+cache_misses)*100:.1f}% hit rate)"
+                f"   📊 JIRA cache: {cache_hits} hits, {cache_misses} misses ({cache_hits / (cache_hits + cache_misses) * 100:.1f}% hit rate)"
             )
 
         # Fetch missing tickets from JIRA

gitflow_analytics/qualitative/chatgpt_analyzer.py

@@ -169,16 +169,16 @@ class ChatGPTQualitativeAnalyzer:
     def _create_executive_summary_prompt(self, summary_data: dict[str, Any]) -> str:
         """Create the prompt for ChatGPT."""
 
-        prompt = f"""Based on the following GitFlow Analytics data from the past {summary_data['period_weeks']} weeks, provide a comprehensive executive summary with qualitative insights:
+        prompt = f"""Based on the following GitFlow Analytics data from the past {summary_data["period_weeks"]} weeks, provide a comprehensive executive summary with qualitative insights:
 
 ## Key Metrics:
-- Total Commits: {summary_data['total_commits']:,}
-- Active Developers: {summary_data['total_developers']}
-- Lines Changed: {summary_data['lines_changed']:,}
-- Story Points Delivered: {summary_data['story_points']}
-- Ticket Coverage: {summary_data['ticket_coverage']:.1f}%
-- Team Health Score: {summary_data['team_health_score']:.1f}/100 ({summary_data['team_health_rating']})
-- Velocity Trend: {summary_data['velocity_trend']}
+- Total Commits: {summary_data["total_commits"]:,}
+- Active Developers: {summary_data["total_developers"]}
+- Lines Changed: {summary_data["lines_changed"]:,}
+- Story Points Delivered: {summary_data["story_points"]}
+- Ticket Coverage: {summary_data["ticket_coverage"]:.1f}%
+- Team Health Score: {summary_data["team_health_score"]:.1f}/100 ({summary_data["team_health_rating"]})
+- Velocity Trend: {summary_data["velocity_trend"]}
 
 ## Top Contributors:
 """
@@ -222,18 +222,18 @@ Report only statistical patterns, measurable trends, and process gaps. Use factu
 
         return f"""## Executive Summary
 
-Over the past {summary_data['period_weeks']} weeks, the development team generated {summary_data['total_commits']:,} commits across {summary_data['total_developers']} active developers.
+Over the past {summary_data["period_weeks"]} weeks, the development team generated {summary_data["total_commits"]:,} commits across {summary_data["total_developers"]} active developers.
 
-The team health score measured {summary_data['team_health_score']:.1f}/100 ({summary_data['team_health_rating']}). Ticket coverage reached {summary_data['ticket_coverage']:.1f}% of total commits with trackable references.
+The team health score measured {summary_data["team_health_score"]:.1f}/100 ({summary_data["team_health_rating"]}). Ticket coverage reached {summary_data["ticket_coverage"]:.1f}% of total commits with trackable references.
 
 ### Measured Outputs:
-- Code changes: {summary_data['lines_changed']:,} lines modified
-- Story points completed: {summary_data['story_points']}
-- Velocity trend: {summary_data['velocity_trend']}
+- Code changes: {summary_data["lines_changed"]:,} lines modified
+- Story points completed: {summary_data["story_points"]}
+- Velocity trend: {summary_data["velocity_trend"]}
 
 ### Process Recommendations:
-1. {'Maintain current output rate' if summary_data['velocity_trend'] == 'increasing' else 'Analyze velocity decline factors'}
-2. {'Sustain current tracking rate' if summary_data['ticket_coverage'] > 60 else 'Increase commit-ticket linking to reach 70% coverage target'}
+1. {"Maintain current output rate" if summary_data["velocity_trend"] == "increasing" else "Analyze velocity decline factors"}
+2. {"Sustain current tracking rate" if summary_data["ticket_coverage"] > 60 else "Increase commit-ticket linking to reach 70% coverage target"}
 3. Review projects with health scores below 60/100 for process gaps
 
 *Note: This is a fallback summary. For detailed analysis, configure ChatGPT integration.*

gitflow_analytics/qualitative/classifiers/llm/prompts.py

@@ -353,7 +353,7 @@ Response (format: CATEGORY confidence reasoning):""",
         """
         formatted = []
         for i, example in enumerate(examples, 1):
-            formatted.append(f"{i}. Message: \"{example['message']}\"")
+            formatted.append(f'{i}. Message: "{example["message"]}"')
             formatted.append(f"   Response: {example['response']}")
         return "\n".join(formatted)
 

gitflow_analytics/qualitative/core/processor.py

@@ -577,8 +577,7 @@ class QualitativeProcessor:
         llm_pct = (llm_processed / total_commits) * 100 if total_commits > 0 else 0
 
         self.logger.info(
-            f"Processing breakdown: {cache_pct:.1f}% cached, "
-            f"{nlp_pct:.1f}% NLP, {llm_pct:.1f}% LLM"
+            f"Processing breakdown: {cache_pct:.1f}% cached, {nlp_pct:.1f}% NLP, {llm_pct:.1f}% LLM"
         )
 
     def _should_optimize_cache(self) -> bool:

gitflow_analytics/qualitative/enhanced_analyzer.py

@@ -906,7 +906,9 @@ class EnhancedQualitativeAnalyzer:
                 "status": (
                     "excellent"
                     if activity_score >= 80
-                    else "good" if activity_score >= 60 else "needs_improvement"
+                    else "good"
+                    if activity_score >= 60
+                    else "needs_improvement"
                 ),
             },
             "contributor_diversity": {
@@ -915,7 +917,9 @@ class EnhancedQualitativeAnalyzer:
                 "status": (
                     "excellent"
                     if len(contributors) >= 4
-                    else "good" if len(contributors) >= 2 else "concerning"
+                    else "good"
+                    if len(contributors) >= 2
+                    else "concerning"
                 ),
             },
             "pr_velocity": {
@@ -929,7 +933,9 @@ class EnhancedQualitativeAnalyzer:
                 "status": (
                     "excellent"
                     if ticket_coverage >= 80
-                    else "good" if ticket_coverage >= 60 else "needs_improvement"
+                    else "good"
+                    if ticket_coverage >= 60
+                    else "needs_improvement"
                 ),
             },
         }
@@ -948,7 +954,9 @@ class EnhancedQualitativeAnalyzer:
             "status": (
                 "excellent"
                 if overall_score >= 80
-                else "good" if overall_score >= 60 else "needs_improvement"
+                else "good"
+                if overall_score >= 60
+                else "needs_improvement"
             ),
         }
 
@@ -1918,7 +1926,9 @@ class EnhancedQualitativeAnalyzer:
                 "status": (
                     "excellent"
                     if ticket_coverage >= 80
-                    else "good" if ticket_coverage >= 60 else "needs_improvement"
+                    else "good"
+                    if ticket_coverage >= 60
+                    else "needs_improvement"
                 ),
             },
             "message_quality": {
@@ -1926,7 +1936,9 @@ class EnhancedQualitativeAnalyzer:
                 "status": (
                     "excellent"
                     if message_quality >= 80
-                    else "good" if message_quality >= 60 else "needs_improvement"
+                    else "good"
+                    if message_quality >= 60
+                    else "needs_improvement"
                 ),
             },
             "commit_size_compliance": {
@@ -1934,7 +1946,9 @@ class EnhancedQualitativeAnalyzer:
                 "status": (
                     "excellent"
                     if size_compliance >= 80
-                    else "good" if size_compliance >= 60 else "needs_improvement"
+                    else "good"
+                    if size_compliance >= 60
+                    else "needs_improvement"
                 ),
             },
             "pr_approval_rate": {"score": pr_approval_rate, "status": "good"},  # Placeholder
@@ -1986,7 +2000,9 @@ class EnhancedQualitativeAnalyzer:
             "collaboration_level": (
                 "high"
                 if collaboration_score >= 70
-                else "medium" if collaboration_score >= 40 else "low"
+                else "medium"
+                if collaboration_score >= 40
+                else "low"
             ),
             "patterns": {
                 "multi_project_engagement": cross_collaboration_rate >= 50,

gitflow_analytics/ui/progress_display.py

@@ -457,12 +457,16 @@ class RichProgressDisplay:
             mem_icon = (
                 "🟢"
                 if self.statistics.memory_usage < 500
-                else "🟡" if self.statistics.memory_usage < 1000 else "🔴"
+                else "🟡"
+                if self.statistics.memory_usage < 1000
+                else "🔴"
             )
             cpu_icon = (
                 "🟢"
                 if self.statistics.cpu_percent < 50
-                else "🟡" if self.statistics.cpu_percent < 80 else "🔴"
+                else "🟡"
+                if self.statistics.cpu_percent < 80
+                else "🔴"
             )
             system_stats.append(f"{mem_icon} Memory: {self.statistics.memory_usage:.0f} MB")
             system_stats.append(f"{cpu_icon} CPU: {self.statistics.cpu_percent:.1f}%")
@@ -471,7 +475,9 @@ class RichProgressDisplay:
             speed_icon = (
                 "🚀"
                 if self.statistics.processing_speed > 100
-                else "⚡" if self.statistics.processing_speed > 50 else "🐢"
+                else "⚡"
+                if self.statistics.processing_speed > 50
+                else "🐢"
             )
             system_stats.append(
                 f"{speed_icon} Speed: {self.statistics.processing_speed:.1f} commits/s"
@@ -484,7 +490,9 @@ class RichProgressDisplay:
         phase_indicator = (
             "⚙️"
             if "Processing" in self.statistics.current_phase
-            else "🔍" if "Analyzing" in self.statistics.current_phase else "✨"
+            else "🔍"
+            if "Analyzing" in self.statistics.current_phase
+            else "✨"
         )
         phase_text = f"{phase_indicator} [bold green]{self.statistics.current_phase}[/bold green]"
         elapsed_text = f"⏱️ [bold blue]{self.statistics.get_elapsed_time()}[/bold blue]"
@@ -1250,9 +1258,9 @@ class SimpleProgressDisplay:
     # Compatibility methods for CLI interface
     def show_header(self):
         """Display header - compatibility method for CLI."""
-        print(f"\n{'='*60}")
+        print(f"\n{'=' * 60}")
         print(f"GitFlow Analytics v{self.version}")
-        print(f"{'='*60}\n")
+        print(f"{'=' * 60}\n")
 
     def start_live_display(self):
         """Start live display - compatibility wrapper for start()."""

gitflow_analytics/verify_activity.py

@@ -636,7 +636,7 @@ class ActivityVerifier:
             # Group consecutive days
             lines.append(f"Found {len(zero_activity_days)} days with no activity:")
             for i in range(0, len(zero_activity_days), 7):
-                lines.append(f"  {', '.join(zero_activity_days[i:i+7])}")
+                lines.append(f"  {', '.join(zero_activity_days[i : i + 7])}")
         else:
             lines.append("No days with zero activity found!")
 

{gitflow_analytics-3.13.0.dist-info → gitflow_analytics-3.13.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitflow-analytics
-Version: 3.13.0
+Version: 3.13.6
 Summary: Analyze Git repositories for developer productivity insights
 Author-email: Bob Matyas <bobmatnyc@gmail.com>
 License: MIT
@@ -1183,6 +1183,42 @@ gitflow-analytics analyze -c config.yaml --debug
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/bobmatnyc/gitflow-analytics.git
+cd gitflow-analytics
+
+# Install development dependencies
+make install-dev
+
+# Run tests
+make test
+
+# Format code
+make format
+
+# Run all quality checks
+make quality-gate
+```
+
+### Release Workflow
+
+This project uses a Makefile-based release workflow for simplicity and transparency. See [RELEASE.md](RELEASE.md) for detailed documentation.
+
+**Quick Reference:**
+```bash
+make release-patch   # Bug fixes (3.13.1 → 3.13.2)
+make release-minor   # New features (3.13.1 → 3.14.0)
+make release-major   # Breaking changes (3.13.1 → 4.0.0)
+```
+
+For more details, see:
+- [RELEASE.md](RELEASE.md) - Comprehensive release guide
+- [RELEASE_QUICKREF.md](RELEASE_QUICKREF.md) - Quick reference card
+- `make help` - All available commands
+
 ## License
 
 This project is licensed under the MIT License - see the LICENSE file for details.