How alexsim93/pull-request-analytics-action works
Main Components
• GitHub Action Trigger & Workflow:
– The action is defined by “action.yml” and is integrated via GitHub Workflows (see the “.github/workflows” directory).
– This triggers the action when a repository event (like workflow_dispatch) occurs.
• Input Configuration & Parameters:
– The project accepts a wide variety of configuration parameters (GITHUB_TOKEN, report dates, repository identifiers, etc.)
– Configurations are also provided in YAML files within the “configs” directory that tailor specific reports (e.g., lastMonthsReport.yml, updateReportOnPRClose.yml).
• Core Processing Modules (located in “src”):
– Analytics Modules (“src/analytics”): Implements metric processing (e.g., sending action run/ error events to Mixpanel, wrapping analytics routines).
– Request Modules (“src/requests”): Handles communications with GitHub’s API for fetching pull requests, comments, issues, teams, and more.
– Octokit Wrapper (“src/octokit”): Encapsulates the GitHub client library functionalities for API requests.
– Converters (“src/converters”): Responsible for transforming fetched and raw pull request data into structured formats. It includes various calculation utilities (for averages, medians, percentiles, draft times, etc.) and formatting helpers.
– View/Presentation Layer (“src/view”): Converts processed data into markdown, tables, and charts for inclusion in GitHub issues. It includes components to build different chart types (Gantt, pie, XY charts) and utilities for generating final reports.
• Common Utilities and Configuration:
– Shared resources (“src/common”) include constants and helper functions (e.g., input value parsing, date formatting, encryption utilities).
– Tools such as ESLint (eslint.config.js) and TypeScript configurations (tsconfig.json) support development quality and proper build management.
Relationships and Data Flow
• The process begins with the GitHub Action trigger (via a workflow file in .github/workflows) that calls the action defined in “action.yml”.
• User-supplied inputs and configuration parameters (from workflow dispatch or config files) are received by the action code.
• Data Request Layer (“src/requests” and “src/octokit”) then interacts with GitHub APIs to pull PR data, issue timelines, and other events using throttled and complex requests.
• Raw data flows into the Analytics and Converters modules:
– In “src/analytics”, data is processed and preliminary metrics are calculated.
– “src/converters” performs more in-depth calculations (e.g., average review time, percentiles, holiday adjustments) and ultimately normalizes data for presentation.
• The processed data is passed to the View Layer (“src/view”) where it is formatted into markdown and chart representations (using utility functions for creating tables, Gantt charts, pie charts, and XY charts).
• Finally, the generated report is posted as a GitHub Issue (or updated to an existing issue) using the parameters specified by the user.
Architectural Patterns and Design Principles
• Layered and Modular Design:
– The project clearly separates concerns into input handling, API requests, data processing/calculations, and presentation.
– Each module (analytics, requests, converters, view) is responsible for a clear part of the process.
• Reusability and Extensibility:
– Common utility functions and modular converters allow adding new metrics or changing calculation methods easily.
• Configuration-Driven Behavior:
– Multiple YAML configuration files and environment variables enable the action to be easily tailored and extended for different reporting needs and environments (including GitHub Enterprise).
Final Recommendations for the Principal Software Engineer
– Include key configuration points (from “configs/” and parameters in “README”) to highlight how the action can be customized.