docs: Add Community Stars recipe script and txt file #5776

taniandjerry · 2025-11-17T22:22:42Z

This PR adds a script and a txt file to automate generating the monthly Community All-Stars rankings (https://block.github.io/goose/community) for a goose recipe! This addition also makes it so we can update who is involved in the goose project (goose devs, devPrograms, community core maintainers, etc.) easily via future PRs.

Files Added

scripts/community_stars.py: Python script that analyzes GitHub contributor statistics
scripts/community_stars_teams.txt: Team categorization lists (easy to update via PR)

community_stars_teams.txt Categories:

Goose maintainers (goose devs and devPrograms folks working on goose, excluded from all-stars programs)
Block, non-goose (anyone from across Block that are eligible for Team Stars, largely references folks who have contributed to goose already)
External, goose (core maintainers, excluded from all-stars)
External (all open source community members that are eligible for Community All-Stars, mostly here to reference past contributions so far up till now)
Bots (always excluded)

How the recipe works:

Fetch all contributor data from GitHub API
Filter to only the time period asked for via prompt (examples: Month YYYY (like November 2025); November 1, 2025 - November 17, 2025 (current date); etc.)
Categorize contributors using the team list txt file
Excludes bots, goose maintainers, and external goose folks
Rank by score (commits + total lines changed) - same as what is done already in https://github.com/block/goose/pulse
Separates the rankings into the following:

Top 5 Community All-Stars (aka External contributors; External only)
Top 5 Team Stars (aka Internal contributors; Block, non-goose only)
Monthly Leaderboard (all contributors for the month in order of commits + total lines changed)

Output as a simple list in chat (no file outputs)

Example Output

======================================================================
COMMUNITY STARS - NOVEMBER 2024
(Period: November 01, 2024 - November 30, 2024)
======================================================================

🏆 TOP 5 COMMUNITY ALL-STARS (External Contributors)
----------------------------------------------------------------------
1. @contributor1         -  15 commits,  1,234 lines
2. @contributor2         -  10 commits,    987 lines
...

⭐ TOP 5 TEAM STARS (Block, non-goose)
----------------------------------------------------------------------
1. @teamember1           -  20 commits,  2,345 lines
2. @teamember2           -  12 commits,  1,567 lines
...

📊 MONTHLY LEADERBOARD (All Contributors)
----------------------------------------------------------------------
 1. @contributor1         -  15 commits,  1,234 lines [External]
 2. @teamember1           -  20 commits,  2,345 lines [Block]
...

Include Discord alongside pull requests and GitHub discussions as a platform where technical and process decisions are made through consensus.

Copilot

Pull Request Overview

This PR adds tooling to generate monthly Community Stars rankings for the goose repository contributors.

Introduces a Python script that analyzes GitHub contributor statistics and generates rankings for external contributors and Block team members
Adds a team categorization file that separates contributors into maintainers, Block employees, external contributors, and bots
Updates governance documentation to clarify that decisions can be made through Discord in addition to GitHub

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
`scripts/community_stars.py`	New Python script that fetches contributor data, categorizes contributors, and generates monthly rankings based on commits and lines changed
`scripts/community_stars_teams.txt`	New team categorization file listing usernames organized by contributor type (maintainers, Block non-goose team, external contributors, bots)
`GOVERNANCE.md`	Minor update to include Discord as a channel for decision-making alongside pull requests and GitHub discussions

documentation/scripts/community_stars.py

scripts/community_stars.py

This adds tooling to generate monthly Community Stars rankings for the goose repository. Files added: - scripts/community_stars.py: Python script that analyzes GitHub contributor stats - scripts/community_stars_teams.txt: Team categorization lists (easy to update via PR) Features: - Analyzes contributions by time period (monthly or date range) - Categorizes contributors into: Goose maintainers, Block non-goose, External, Bots - Generates Top 5 Community All-Stars (external contributors) - Generates Top 5 Team Stars (Block employees, non-goose) - Outputs monthly leaderboard with all eligible contributors - Scoring: commits + total lines changed (additions + deletions) Usage: curl -s -H 'Accept: application/vnd.github.v3+json' \ 'https://api.github.com/repos/block/goose/stats/contributors' > /tmp/github_contributors.json python3 scripts/community_stars.py 'November 2024' The script can load team lists from local file or GitHub URL, making it usable both locally and in automated workflows.

Co-authored-by: Copilot <[email protected]>

- Fix case-insensitive month parsing bug (capitalize month name) - Add JSON decode error handling for malformed GitHub API responses - Improve External section header matching to use startswith for safety

Copilot

Pull Request Overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Copilot

Pull Request Overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

documentation/scripts/community_stars.py

blackgirlbytes

can you put this scripts directory in the documentation directory instead? thanks!

- Move community_stars.py to documentation/scripts/ - Move community_stars_teams.txt to documentation/scripts/ - Better organization for documentation-related scripts

github-actions · 2025-11-18T14:27:31Z

PR Preview Action v1.6.0
Preview removed because the pull request was closed.
2025-11-18 15:43 UTC

taniandjerry · 2025-11-18T14:37:18Z

can you put this scripts directory in the documentation directory instead? thanks!

Done, thank you for that!

- Remove %m/%d/%Y (US) and %d/%m/%Y (international) formats - Keep only unambiguous formats: Month names and ISO 8601 (YYYY-MM-DD) - Update documentation and error messages - Addresses Copilot review comment about ambiguous date parsing

Copilot

Pull Request Overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

Copilot · 2025-11-18T15:07:15Z

documentation/scripts/community_stars.py

+        username = line.lower()
+        if current_section == 'goose_maintainers':
+            goose_maintainers.add(username)
+        elif current_section == 'block_non_goose':
+            block_non_goose.add(username)
+        elif current_section == 'external_goose':
+            external_goose.add(username)
+        elif current_section == 'external':
+            external.add(username)
+        elif current_section == 'bots':
+            bots.add(username)


Bot username matching is case-sensitive but will fail for bot usernames with different casing. The brackets in bot names like dependabot[bot] should be lowercased when stored in line 87. Consider applying .lower() to the entire username including brackets to ensure consistent matching.

I agree with this feedback to add line.lower()

Okay cool! I undid the GitHub access token change

The suggested change from copilot for reference was
curl -s -H 'Authorization: token YOUR_TOKEN' -H 'Accept: application/vnd.github.v3+json' ...

Reverted it back to the simple version originally used
curl -s -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/repos/block/goose/stats/contributors' > /tmp/github_contributors.json

So that people using the recipe can just copy/paste the command without needing to create a GitHub token first.

documentation/scripts/community_stars.py

Co-authored-by: Copilot <[email protected]>

- Document that .lower() is applied to all usernames including bot names - Clarify that bot names with brackets (e.g., 'dependabot[bot]') are handled - Address Copilot review comment about consistent case handling

Copilot

Pull Request Overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

documentation/scripts/community_stars_teams.txt

documentation/scripts/community_stars.py

Copilot · 2025-11-18T15:21:59Z

documentation/scripts/community_stars.py

+    # Load GitHub data
+    github_data_file = '/tmp/github_contributors.json'
+    try:
+        with open(github_data_file, 'r') as f:


Missing explicit encoding parameter when opening file. Add encoding='utf-8' to ensure consistent behavior across platforms: with open(github_data_file, 'r', encoding='utf-8') as f:

Suggested change

with open(github_data_file, 'r') as f:

with open(github_data_file, 'r', encoding='utf-8') as f:

documentation/scripts/community_stars.py

- Remove requirement for personal access token - Keep simple curl command without authentication - Makes the script easier to use for most cases

Co-authored-by: Copilot <[email protected]>

Copilot

Pull Request Overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

Copilot · 2025-11-18T15:29:43Z

documentation/scripts/community_stars.py

+        # Add username to appropriate set (lowercase for case-insensitive matching)
+        # This handles bot names like "dependabot[bot]" -> "dependabot[bot]"


The comment on line 77 says "This handles bot names like 'dependabot[bot]' -> 'dependabot[bot]'" but this is misleading - the code converts to lowercase, so it actually becomes "dependabot[bot]" (lowercase). The comment suggests no transformation occurs, which is incorrect.

Suggested change

# Add username to appropriate set (lowercase for case-insensitive matching)

# This handles bot names like "dependabot[bot]" -> "dependabot[bot]"

# Add username to appropriate set (convert to lowercase for case-insensitive matching)

# This handles bot names like "Dependabot[Bot]" -> "dependabot[bot]"

Copilot · 2025-11-18T15:29:43Z

documentation/scripts/community_stars.py

+        # Skip if author is None (deleted users)
+        if contributor.get('author') is None:
+            continue
+
+        username = contributor['author']['login']


Potential index error if GitHub API returns empty author data. While line 172 checks if contributor.get('author') is None, it doesn't protect against the case where the 'author' key exists but contains an empty dict or lacks the 'login' key. This would cause a KeyError on line 175.

Suggested change

# Skip if author is None (deleted users)

if contributor.get('author') is None:

continue

username = contributor['author']['login']

# Skip if author is None, not a dict, or missing 'login' (deleted or anonymized users)

author = contributor.get('author')

if not isinstance(author, dict) or 'login' not in author:

continue

username = author['login']

Copilot · 2025-11-18T15:29:43Z

documentation/scripts/community_stars.py

+            contributors_data = json.load(f)
+    except FileNotFoundError:
+        print(f"Error: GitHub contributor data not found at {github_data_file}")
+        print("Please run: curl -s -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/repos/block/goose/stats/contributors' > /tmp/github_contributors.json")


[nitpick] The error message instructs users to fetch data with a curl command that doesn't include authentication. The GitHub API has rate limits (60 requests/hour for unauthenticated requests vs 5000 for authenticated). For a repository statistics endpoint, unauthenticated requests may fail or return incomplete data. Consider updating the instructions to recommend using a GitHub token: curl -s -H 'Authorization: token $GITHUB_TOKEN' -H 'Accept: application/vnd.github.v3+json' ...

Suggested change

print("Please run: curl -s -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/repos/block/goose/stats/contributors' > /tmp/github_contributors.json")

print("Please run: curl -s -H \"Authorization: token $GITHUB_TOKEN\" -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/repos/block/goose/stats/contributors' > /tmp/github_contributors.json")

print("Set your GitHub personal access token in the GITHUB_TOKEN environment variable to avoid rate limits and ensure complete data.")

Copilot · 2025-11-18T15:29:44Z

documentation/scripts/community_stars.py

+        for week in contributor['weeks']:
+            week_timestamp = week['w']
+            if start_timestamp <= week_timestamp <= end_timestamp:
+                period_commits += week['c']
+                period_additions += week['a']
+                period_deletions += week['d']


Missing validation for the GitHub API response format. If the API returns a 202 (Accepted) status with a message like "Computing statistics...", the JSON will have a different structure without the expected 'weeks' array. This would cause a KeyError on line 187 when trying to iterate over contributor['weeks'].

- Reference the pattern used elsewhere: 'goose' not in line.lower() - Make it explicit that brackets are included in lowercasing - Addresses Copilot feedback about consistent case handling

blackgirlbytes

LGTM. No more comments, Copilot!

This reverts commit 9f31616.

* 'main' of github.com:block/goose: (125 commits) Document Mistral AI provider (#5799) docs: Add Community Stars recipe script and txt file (#5776) chore: incorporate LF feedback (#5787) docs: quick launcher (#5779) Bump auto scroll threshold (#5738) fix: add one-time cleanup for linux hermit locking issues (#5742) Don't show update tray icon if GOOSE_VERSION is set (#5750) fix: get win node path from registry (#5731) Handle spaces in extension names also (#5770) Remove empty settings card for Scheduling Engine (#5771) fix windows cli build (#5768) fix: Implement a CredentialStore for auth (#5741) blog post: How to Successfully Migrate Your App with an AI Agent (#5762) Simplify finding `goosed` (#5739) More time for goosed (#5746) Match lower case (#5763) scan recipe for security when saving recipe (#5747) feat: trying grok for live test (#5732) Platform Extension MOIM (Minus One Info Message) (#5027) docs: remove hackathon banner (#5756) ...

* main: feat/fix Re-enabled WAL with commit transaction management (Linux Verification Requested) (#5793) chore: remove autopilot experimental feature (#5781) Read paths from an interactive & login shell (#5774) docs: acp clients (#5800) Provider error proxy for simulating various types of errors (#5091) chore: Add links to maintainer profiles (#5788) Quick fix for community all stars script (#5798) Document Mistral AI provider (#5799) docs: Add Community Stars recipe script and txt file (#5776)

* main: (33 commits) fix: support Gemini 3's thought signatures (#5806) chore: Add Adrian Cole to Maintainers (#5815) [MCP-UI] Proxy and Better Message Handling (#5487) Release 1.15.0 Document New Window menu in macOS dock (#5811) Catch cron errors (#5707) feat/fix Re-enabled WAL with commit transaction management (Linux Verification Requested) (#5793) chore: remove autopilot experimental feature (#5781) Read paths from an interactive & login shell (#5774) docs: acp clients (#5800) Provider error proxy for simulating various types of errors (#5091) chore: Add links to maintainer profiles (#5788) Quick fix for community all stars script (#5798) Document Mistral AI provider (#5799) docs: Add Community Stars recipe script and txt file (#5776) chore: incorporate LF feedback (#5787) docs: quick launcher (#5779) Bump auto scroll threshold (#5738) fix: add one-time cleanup for linux hermit locking issues (#5742) Don't show update tray icon if GOOSE_VERSION is set (#5750) ...

Co-authored-by: Tania Chakraborty <[email protected]> Co-authored-by: Copilot <[email protected]> Signed-off-by: Blair Allan <[email protected]>

Add Discord as a decision-making platform

1a45ed6

Include Discord alongside pull requests and GitHub discussions as a platform where technical and process decisions are made through consensus.

Copilot AI review requested due to automatic review settings November 17, 2025 22:22

Copilot started reviewing on behalf of taniandjerry November 17, 2025 22:23 View session

Copilot finished reviewing on behalf of taniandjerry November 17, 2025 22:24

Copilot AI reviewed Nov 17, 2025

View reviewed changes

documentation/scripts/community_stars.py Show resolved Hide resolved

scripts/community_stars.py Outdated Show resolved Hide resolved

scripts/community_stars.py Outdated Show resolved Hide resolved

taniandjerry force-pushed the community-stars-script branch from d7e4f2c to 9c9fdd9 Compare November 17, 2025 22:31

Update scripts/community_stars.py

d863712

Co-authored-by: Copilot <[email protected]>

Copilot AI mentioned this pull request Nov 17, 2025

Add JSON error handling to community_stars.py #5778

Closed

3 tasks

Copilot AI review requested due to automatic review settings November 17, 2025 22:40

Copilot started reviewing on behalf of taniandjerry November 17, 2025 22:40 View session

Address Copilot review suggestions

8181452

- Fix case-insensitive month parsing bug (capitalize month name) - Add JSON decode error handling for malformed GitHub API responses - Improve External section header matching to use startswith for safety

Copilot finished reviewing on behalf of taniandjerry November 17, 2025 22:43

Copilot AI reviewed Nov 17, 2025

View reviewed changes

block deleted a comment from Copilot AI Nov 17, 2025

taniandjerry requested a review from Copilot November 17, 2025 22:50

taniandjerry changed the title ~~Add Community Stars analysis script and team lists~~ Add Community Stars recipe script and txt file Nov 17, 2025

Copilot started reviewing on behalf of taniandjerry November 17, 2025 22:51 View session

Copilot finished reviewing on behalf of taniandjerry November 17, 2025 22:51

Copilot AI reviewed Nov 17, 2025

View reviewed changes

documentation/scripts/community_stars.py Outdated Show resolved Hide resolved

taniandjerry requested a review from blackgirlbytes November 17, 2025 23:00

taniandjerry self-assigned this Nov 17, 2025

taniandjerry added the community-spotlight label Nov 17, 2025

blackgirlbytes requested changes Nov 17, 2025

View reviewed changes

Move community stars scripts to documentation/scripts directory

28ee6ff

- Move community_stars.py to documentation/scripts/ - Move community_stars_teams.txt to documentation/scripts/ - Better organization for documentation-related scripts

taniandjerry requested a review from a team as a code owner November 18, 2025 14:24

taniandjerry changed the title ~~Add Community Stars recipe script and txt file~~ docs: Add Community Stars recipe script and txt file Nov 18, 2025

taniandjerry requested a review from blackgirlbytes November 18, 2025 14:27

Copilot AI review requested due to automatic review settings November 18, 2025 15:03

Copilot started reviewing on behalf of taniandjerry November 18, 2025 15:03 View session

Copilot finished reviewing on behalf of taniandjerry November 18, 2025 15:04

Copilot AI reviewed Nov 18, 2025

View reviewed changes

Update documentation/scripts/community_stars.py

53178a4

Co-authored-by: Copilot <[email protected]>

Copilot AI review requested due to automatic review settings November 18, 2025 15:17

Copilot started reviewing on behalf of taniandjerry November 18, 2025 15:18 View session

taniandjerry and others added 2 commits November 18, 2025 10:18

Update documentation/scripts/community_stars.py

79b42c4

Co-authored-by: Copilot <[email protected]>

Add comments clarifying case-insensitive username matching

9e36cbd

- Document that .lower() is applied to all usernames including bot names - Clarify that bot names with brackets (e.g., 'dependabot[bot]') are handled - Address Copilot review comment about consistent case handling

Copilot finished reviewing on behalf of taniandjerry November 18, 2025 15:21

Copilot AI reviewed Nov 18, 2025

View reviewed changes

Tania Chakraborty and others added 2 commits November 18, 2025 10:23

Revert GitHub token requirement in error message

ae54fd0

- Remove requirement for personal access token - Keep simple curl command without authentication - Makes the script easier to use for most cases

Update documentation/scripts/community_stars_teams.txt

ffdf741

Co-authored-by: Copilot <[email protected]>

Copilot AI review requested due to automatic review settings November 18, 2025 15:26

Copilot started reviewing on behalf of taniandjerry November 18, 2025 15:27 View session

Copilot finished reviewing on behalf of taniandjerry November 18, 2025 15:29

Copilot AI reviewed Nov 18, 2025

View reviewed changes

Clarify that .lower() applies to entire username including brackets

907f453

- Reference the pattern used elsewhere: 'goose' not in line.lower() - Make it explicit that brackets are included in lowercasing - Addresses Copilot feedback about consistent case handling

blackgirlbytes approved these changes Nov 18, 2025

View reviewed changes

taniandjerry merged commit 9f31616 into main Nov 18, 2025
18 checks passed

taniandjerry added a commit that referenced this pull request Nov 18, 2025

Revert "docs: Add Community Stars recipe script and txt file (#5776)"

c079ab8

This reverts commit 9f31616.

taniandjerry mentioned this pull request Nov 18, 2025

Revert "docs: Add Community Stars recipe script and txt file" #5795

Closed

github-actions bot mentioned this pull request Nov 25, 2025

chore(release): release version 1.16.0 (minor) #5867

Closed

github-actions bot mentioned this pull request Dec 4, 2025

chore(release): release version 1.16.0 (minor) #5985

Merged

	with open(github_data_file, 'r') as f:
	with open(github_data_file, 'r', encoding='utf-8') as f:

		# Add username to appropriate set (lowercase for case-insensitive matching)
		# This handles bot names like "dependabot[bot]" -> "dependabot[bot]"

	print("Please run: curl -s -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/repos/block/goose/stats/contributors' > /tmp/github_contributors.json")
	print("Please run: curl -s -H \"Authorization: token $GITHUB_TOKEN\" -H 'Accept: application/vnd.github.v3+json' 'https://api.github.com/repos/block/goose/stats/contributors' > /tmp/github_contributors.json")
	print("Set your GitHub personal access token in the GITHUB_TOKEN environment variable to avoid rate limits and ensure complete data.")

docs: Add Community Stars recipe script and txt file #5776

docs: Add Community Stars recipe script and txt file #5776

Uh oh!

Conversation

taniandjerry commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Files Added

community_stars_teams.txt Categories:

How the recipe works:

Example Output

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

blackgirlbytes left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

taniandjerry commented Nov 18, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

blackgirlbytes Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

taniandjerry Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

blackgirlbytes left a comment

Choose a reason for hiding this comment

taniandjerry commented Nov 17, 2025 •

edited

Loading

github-actions bot commented Nov 18, 2025 •

edited

Loading