GH#4097: Make partial results explicit in contributor-activity-helper.sh

[alex-solovyev]

Summary

• When person_stats() hits GitHub Search API rate limits mid-run, it now returns exit code 75 (EX_TEMPFAIL) and emits <!-- partial-results --> HTML comment, so callers can distinguish complete from truncated results
• cross_repo_person_stats() now handles EX_PARTIAL from sub-calls and propagates the flag in both JSON and markdown output

Closes #4097

Summary by CodeRabbit

• New Features

  • Reports now clearly indicate when results are partial or incomplete
  • Added partial-result status flags to JSON and markdown output formats

• Improvements

  • Enhanced detection and propagation of incomplete data status across multi-repository aggregations
  • Improved handling ensures partial results are still delivered with appropriate markers

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the contributor-activity-helper.sh script by introducing robust handling for GitHub API rate limits. It ensures that when data retrieval is incomplete due to rate limiting, the script explicitly communicates this partial status through distinct exit codes, HTML comments, and JSON flags. This allows callers to reliably differentiate between complete and truncated results, improving data integrity and enabling better caching strategies for incomplete data.

Highlights

• Explicit Partial Results: The person_stats() function now explicitly indicates partial results when GitHub Search API rate limits are hit mid-run. It returns exit code 75 (EX_TEMPFAIL) and emits an HTML comment <!-- partial-results --> in markdown output, or includes "partial": true in JSON output.
• Partial Result Propagation: The cross_repo_person_stats() function has been updated to handle and propagate the EX_PARTIAL status from its sub-calls, ensuring that aggregated results also correctly reflect if any underlying data was partial.
• Standardized Exit Code: A new EX_PARTIAL constant (value 75, corresponding to EX_TEMPFAIL from sysexits.h) has been introduced to clearly distinguish between complete success (0), general errors (1), and valid but truncated results due to temporary failures like rate limiting.

Changelog

• .agents/scripts/contributor-activity-helper.sh
  • Added detailed documentation for exit codes, including the new EX_PARTIAL (75) for partial results.
  • Defined readonly EX_PARTIAL=75 to standardize the exit code for partial results.
  • Modified person_stats to print <!-- partial-results --> and return EX_PARTIAL when _ps_partial is true.
  • Updated cross_repo_person_stats to capture the exit code of person_stats sub-calls and set an internal _crps_any_partial flag if EX_PARTIAL is returned.
  • Adjusted cross_repo_person_stats to pass the _crps_any_partial status to the Python script as an argument.
  • Modified the Python script to accept and process the is_partial argument.
  • Updated the Python script to include a "partial": true field in the JSON output when results are partial.
  • Ensured cross_repo_person_stats prints <!-- partial-results --> in markdown output and returns EX_PARTIAL if any aggregated data was partial.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

The PR implements explicit partial-result handling in the contributor-activity-helper.sh script by introducing a distinct exit code (EX_PARTIAL=75), emitting partial indicators in JSON and markdown outputs, and propagating partial-result state through per-repo and cross-repo aggregation functions to prevent callers from treating rate-limited data as complete.

Changes

Cohort / File(s)

Summary

Partial Results Handling .agents/scripts/contributor-activity-helper.sh

Introduces EX_PARTIAL exit code constant; adds "partial" flags to JSON output structures for contributors, repos, and cross-repo summaries; propagates partial-result state through per-repo aggregation (_ps_partial, _crps_any_partial variables) and cross-repo paths (cross-repo-summary, cross-repo-session-time, cross-repo-person-stats); emits partial-results HTML comments and notices in final output when rate limiting truncates data; ensures callers can detect and preserve incomplete payloads.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• t1429: Separate stats from pulse to prevent rate-limit blocking #4094: Addressed the initial quality feedback on partial-result handling; this PR builds upon and refines those changes with comprehensive state propagation.
• feat: separate human vs bot activity in health dashboard #3917: Extended cross-repo aggregation logic (cross_repo_summary) that now carries partial-result state forward through this PR's changes.
• feat: add per-person GitHub output stats #3923: Added person_stats/cross_repo_person_stats flows that are enhanced here with explicit partial-result tracking and propagation.

Suggested labels

enhancement

Poem

🎯 Exit codes now tell the tale—
When rate limits make data pale,
A flag marks partial, clear and bright,
So callers know what's incomplete.
Robustness flows through every stage! 📊

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: making partial results explicit in the contributor-activity-helper script, directly addressing issue #4097.
Linked Issues check	✅ Passed	The pull request successfully implements all requirements from #4097: returns exit code 75 (EX_PARTIAL) for rate-limiting, emits HTML comment marker in outputs, and propagates partial flags through JSON and Markdown rendering.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to addressing #4097 requirements: partial-result signaling, exit code handling, and output marker propagation in contributor-activity-helper.sh.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch chore/gh4097-contributor-activity-quality

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

🔍 Code Quality Report

�[0;35m[MONITOR]�[0m Code Review Monitoring Report

�[0;34m[INFO]�[0m Latest Quality Status:
SonarCloud: 0 bugs, 0 vulnerabilities, 396 code smells

�[0;34m[INFO]�[0m Recent monitoring activity:
Wed Mar 11 02:26:19 UTC 2026: Code review monitoring started
Wed Mar 11 02:26:20 UTC 2026: SonarCloud - Bugs: 0, Vulnerabilities: 0, Code Smells: 396

📈 Current Quality Metrics

• BUGS: 0
• CODE SMELLS: 396
• VULNERABILITIES: 0

Generated on: Wed Mar 11 02:26:23 UTC 2026

---

Generated by AI DevOps Framework Code Review Monitoring

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[gemini-code-assist]

Code Review

This pull request introduces a mechanism to explicitly handle partial results from the GitHub Search API when rate limits are encountered. The changes are well-implemented, adding a new exit code and updating both JSON and markdown outputs to indicate when results are incomplete. This improves the script's robustness and provides clearer feedback to its callers. The code is clean, well-documented, and I have no concerns with the proposed changes.

_{Note: Security Review did not run due to the size of the PR.}