Instructions for Compiling the Weekly Notable Changes Report

This document outlines the comprehensive, step-by-step process for generating the weekly notable changes report for the Flutter repository. Follow these instructions carefully to ensure accuracy and efficiency.

Phase 1: Initial Data Gathering & Curation

1. Fetch Latest Commits: Ensure the local repository is up-to-date by running git fetch.
2. Get All Commits from the Last 7 Days: Get a list of all commits that have landed in the past seven days (inclusive of today). Use the following command to get the commit hash and the subject line:

   git log --since="7 days ago" --pretty=format:"%H - %s"

3. Select Notable Commits: From the full list, select approximately 20 notable commits. Use the following rubric for selection:
   • Prioritize:
     • Developer-Facing Features: New widgets, new properties, or new tool capabilities.
     • Developer Experience Improvements: Better error messages, more consistent tooling.
     • Significant Bug Fixes: Fixes for common crashes, visual glitches, or long-standing issues.
     • Platform & Accessibility: Compatibility with new OS/tool versions (e.g., Xcode) and accessibility improvements.
     • Architectural Significance: Changes that enable future work or represent a new direction (e.g., initial commit for a new renderer).
   • De-prioritize (Generally Exclude):
     • Routine dependency rolls (e.g., Skia, Dart SDK).
     • Minor documentation typos or formatting changes.
     • CI/testing infrastructure tweaks that don't affect developers.
     • Internal code refactoring that doesn't change behavior or API.
4. Extract PR Numbers: For each selected notable commit, extract the pull request number from the commit message (e.g., the number in (#12345)).

Phase 2: Detailed Information Retrieval

For each selected notable PR, gather the following information using the gh CLI tool.

1. Get Author and Approved Reviewers: Use the following precise command to get the PR author and a list of reviewers who explicitly approved the change. This avoids incorrectly attributing reviewers.

   gh pr view <PR_NUMBER> --json author,reviews -q '{author: .author.login, reviewers: [.reviews[] | select(.state=="APPROVED") | .author.login]}'

2. Get Author's Full Name: For each author and reviewer login, get their full name for the report.

   gh api users/<LOGIN> --jq .name

   Note: If a user does not have a public name, use their login instead.
3. Get PR Body for Summary: Get the full PR description, which will be used to write an accurate summary of the change.

   gh pr view <PR_NUMBER> --json body

Phase 3: First-Time Contributor Analysis (CRITICAL)

This is a multi-step process to accurately identify contributors whose first ever commit landed this week.

1. Get All Unique Authors This Week: Get a list of all unique author names and emails from the last 7 days.

   git log --since="7 days ago" --pretty=format:"%an <%ae>" | sort -u

2. Check known_authors.md: Before checking the full git history, check if the author is already listed in the known_authors.md file. If they are, they are not a first-time contributor.
3. Find First Commit Date: For any author not in known_authors.md, find the date of their very first commit in the repository's history. Use their full name and email string from the previous step to be robust against multiple email addresses.

   git log --author="<Full Name <[email protected]>>" --reverse --pretty=format:"%ci" | head -n 1

4. Verify First-Time Status: Compare the commit date to the start of the 7-day window. If the date is within the last 7 days, the author is a first-time contributor for this week.

Phase 4: Drafting the Report

Assemble the gathered information into the notable_changes.md file.

1. Add the Date Heading:
   • Calculate the date range for the report (today and the 6 previous days).
   • Add a heading at the very top of the file in the format: ### MMMM DD, YYYY to MMMM DD, YYYY.
2. Create the Summary:
   • Get the total number of commits: git log --since="7 days ago" --oneline | wc -l
   • Get the current Flutter version: flutter doctor -v
   • Write a brief, engaging summary at the top of the file. Mention the total number of changes, the likely version tag, and the number of new contributors. Include a mention of the Gemini CLI process.
3. Format Notable Changes:
   • Create a section for each category (e.g., Framework, Material, Tool).
   • For each change, use the format: **[#PR_NUMBER](LINK_TO_PR) PR_TITLE**
   • Write a brief, human-readable summary of the change. Base it on the PR description and code diff. The tone should be celebratory but accurate and not overly dramatized. Favor literal descriptions over interpretation. Check the PR body for any images, gifs, or video clips that illustrate the change and embed them in the summary if available.
   • List the author and reviewers using the format: A change from [Full Name](https://github.com/login) (with reviews from [Reviewer 1](...), [Reviewer 2](...))
   • Add 1-2 relevant emojis sparingly and naturally to add personality.
4. Add First-Time Contributor Section:
   • Create a final section titled "First-time Contributors".
   • Add a welcoming message.
   • List each verified first-time contributor with a link to their GitHub profile: - [Full Name](https://github.com/login)

Phase 5: Housekeeping and Finalization

1. Update known_authors.md:
   • For every unique author who contributed this week (both new and existing), add them to the known_authors.md file if they are not already listed. This will speed up the process for next week.
   • Use the format: - [Full Name](https://github.com/login)
2. Final Audit:
   • Read through the entire notable_changes.md file one last time.
   • Check for accuracy in numbers, names, and descriptions.
   • Ensure the tone is appropriate.
3. Commit (With Permission):
   • Stage both notable_changes.md and known_authors.md.
   • CRITICAL: Ask the user for explicit permission before creating a commit. Do not assume.
   • If permission is granted, use a descriptive commit message like: docs: Create weekly notable changes report for YYYY-MM-DD.