From 738349473d66180b28a27ba894490ec541ecc85e Mon Sep 17 00:00:00 2001 From: Nicholas Chammas Date: Fri, 21 Aug 2026 11:46:32 -0400 Subject: [PATCH 1/6] point to origin, not upstream! --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index a5fdef57c29f3..73a5bad5b0a03 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,7 +9,7 @@ Before the first code edit or running test in a session, ensure a clean working 3. If there are uncommitted changes (check with `git status`), ask the user to stash them before proceeding. 4. Switch to the appropriate branch: - **Existing PR**: resolve the PR branch name via `gh api repos/apache/spark/pulls/ --jq '.head.ref'`, then look for a local branch matching that name. If found, switch to it and inform the user. If not found, ask whether to fetch it or if there is a local branch under a different name. - - **New edits**: ask the user to choose: create a new git worktree from `/master` and work from there (recommended), or create and switch to a new branch from `/master`. + - **New edits**: ask the user to choose: create a new git worktree from `/master` and work from there (recommended), or create and switch to a new branch from `/master`. - **Running tests**: use `/master`. ## Development Notes From 7c701e8f550d834bd3a896a03b4aa71343bc86d8 Mon Sep 17 00:00:00 2001 From: Nicholas Chammas Date: Fri, 21 Aug 2026 17:17:23 -0400 Subject: [PATCH 2/6] refactor pre-flight checks --- AGENTS.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 51 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 73a5bad5b0a03..1758533ccee5b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,15 +2,57 @@ ## Pre-flight Checks -Before the first code edit or running test in a session, ensure a clean working environment. DO NOT skip these checks: - -1. Run `git remote -v` to identify the personal fork and upstream (`apache/spark`). If unclear, ask the user to configure their remotes following the standard convention (`origin` for the fork, `upstream` for `apache/spark`). -2. If the latest commit on `/master` is more than a day old (check with `git log -1 --format="%ci" /master`), run `git fetch master`. -3. If there are uncommitted changes (check with `git status`), ask the user to stash them before proceeding. -4. Switch to the appropriate branch: - - **Existing PR**: resolve the PR branch name via `gh api repos/apache/spark/pulls/ --jq '.head.ref'`, then look for a local branch matching that name. If found, switch to it and inform the user. If not found, ask whether to fetch it or if there is a local branch under a different name. - - **New edits**: ask the user to choose: create a new git worktree from `/master` and work from there (recommended), or create and switch to a new branch from `/master`. - - **Running tests**: use `/master`. +Before the first code edit or test in a session, complete these checks: + +1. Run `git remote -v`: both `origin` fetch and push URLs must be the user's personal fork, + and `upstream` must be `apache/spark`. Otherwise, ask the user to configure the remotes. +2. Run `git status`; if there are uncommitted changes, ask the user to stash them. +3. Before creating a branch or worktree from `origin/master`, check the age of the commit at + local `upstream/master` with `git log -1 --format="%ci" upstream/master`. If it is more than + a day old, refresh both refs: + + ```sh + git fetch upstream master + git fetch origin master + ``` +4. Choose the work path: + - **Review or continue work on an existing PR**: resolve its head repository, ref, and SHA: + + ```sh + gh api repos/apache/spark/pulls/ \ + --jq '{repo: .head.repo.full_name, ref: .head.ref, sha: .head.sha}' + ``` + + For a review, use a local branch at the returned SHA. To continue edits, switch to a + matching local branch if one exists and inform the user. If the needed branch is not local, + ask whether to fetch the returned head repository and ref or use a differently named local + branch. + - **New PR**: ask the user to choose: + - **Linked worktree (recommended)**: follow Creating a Worktree below. + - **New branch**: create and switch to a new branch from `origin/master`. + +### Creating a Worktree + +For a new PR or test-only worktree, verify that `origin` is the user's personal fork. Create it +only with: + +```sh +git worktree add -b --track origin/master +``` + +Do not substitute `upstream/master`, omit `--track`, or use `--force`. A branch worktree must +never track or push through `upstream` or `apache` (`apache/spark`). Read or fetch `upstream` only +in the main checkout. + +After creating a linked worktree, before editing files or running tests, run: + +```sh +git -C status -sb +``` + +Proceed only when the status reports `...origin/...`. + +Otherwise, stop and ask the user how to proceed. ## Development Notes From 43d2c8ef3a5c9f42ecfd9317c5a61e580c29cc9d Mon Sep 17 00:00:00 2001 From: Nicholas Chammas Date: Fri, 21 Aug 2026 17:26:43 -0400 Subject: [PATCH 3/6] indentation --- AGENTS.md | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1758533ccee5b..b3db431a10722 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,20 +16,17 @@ Before the first code edit or test in a session, complete these checks: git fetch origin master ``` 4. Choose the work path: - - **Review or continue work on an existing PR**: resolve its head repository, ref, and SHA: - - ```sh - gh api repos/apache/spark/pulls/ \ - --jq '{repo: .head.repo.full_name, ref: .head.ref, sha: .head.sha}' - ``` - - For a review, use a local branch at the returned SHA. To continue edits, switch to a - matching local branch if one exists and inform the user. If the needed branch is not local, - ask whether to fetch the returned head repository and ref or use a differently named local - branch. - - **New PR**: ask the user to choose: - - **Linked worktree (recommended)**: follow Creating a Worktree below. - - **New branch**: create and switch to a new branch from `origin/master`. + - **Review or continue work on an existing PR**: resolve its head repository, ref, and SHA: + + ```sh + gh api repos/apache/spark/pulls/ \ + --jq '{repo: .head.repo.full_name, ref: .head.ref, sha: .head.sha}' + ``` + + For a review, use a local branch at the returned SHA. + - **New PR**: ask the user to choose: + - **Linked worktree (recommended)**: follow "Creating a Worktree" below. + - **New branch**: create and switch to a new branch from `origin/master`. ### Creating a Worktree From 0a505c660d0907e7176eec242a3efe843e54f2bc Mon Sep 17 00:00:00 2001 From: Nicholas Chammas Date: Sat, 22 Aug 2026 11:30:10 -0400 Subject: [PATCH 4/6] revert to minimal `--no-track` tweak --- AGENTS.md | 67 ++++++++++++++++--------------------------------------- 1 file changed, 19 insertions(+), 48 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b3db431a10722..062733c7ce970 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,54 +2,25 @@ ## Pre-flight Checks -Before the first code edit or test in a session, complete these checks: - -1. Run `git remote -v`: both `origin` fetch and push URLs must be the user's personal fork, - and `upstream` must be `apache/spark`. Otherwise, ask the user to configure the remotes. -2. Run `git status`; if there are uncommitted changes, ask the user to stash them. -3. Before creating a branch or worktree from `origin/master`, check the age of the commit at - local `upstream/master` with `git log -1 --format="%ci" upstream/master`. If it is more than - a day old, refresh both refs: - - ```sh - git fetch upstream master - git fetch origin master - ``` -4. Choose the work path: - - **Review or continue work on an existing PR**: resolve its head repository, ref, and SHA: - - ```sh - gh api repos/apache/spark/pulls/ \ - --jq '{repo: .head.repo.full_name, ref: .head.ref, sha: .head.sha}' - ``` - - For a review, use a local branch at the returned SHA. - - **New PR**: ask the user to choose: - - **Linked worktree (recommended)**: follow "Creating a Worktree" below. - - **New branch**: create and switch to a new branch from `origin/master`. - -### Creating a Worktree - -For a new PR or test-only worktree, verify that `origin` is the user's personal fork. Create it -only with: - -```sh -git worktree add -b --track origin/master -``` - -Do not substitute `upstream/master`, omit `--track`, or use `--force`. A branch worktree must -never track or push through `upstream` or `apache` (`apache/spark`). Read or fetch `upstream` only -in the main checkout. - -After creating a linked worktree, before editing files or running tests, run: - -```sh -git -C status -sb -``` - -Proceed only when the status reports `...origin/...`. - -Otherwise, stop and ask the user how to proceed. +Before the first code edit or running test in a session, ensure a clean working +environment. DO NOT skip these checks: + +1. Run `git remote -v` to identify the personal fork and upstream (`apache/spark`). If unclear, + ask the user to configure their remotes following the standard convention (`origin` for the + fork, `upstream` for `apache/spark`). +2. If the latest commit on `/master` is more than a day old (check with + `git log -1 --format="%ci" /master`), run `git fetch master`. +3. If there are uncommitted changes (check with `git status`), ask the user to stash them before + proceeding. +4. Switch to the appropriate branch: + - **Existing PR**: resolve the PR branch name via `gh api repos/apache/spark/pulls/ --jq + '.head.ref'`, then look for a local branch matching that name. If found, switch to it and + inform the user. If not found, ask whether to fetch it or if there is a local branch under a + different name. + - **New edits**: ask the user to choose: create a new git worktree from + `/master` with `--no-track` and work from there (recommended), or + create and switch to a new branch from `/master` with `--no-track`. + - **Running tests**: use `/master`. ## Development Notes From 23dfed8eec0700af5e43233aa6bde1ed1c798592 Mon Sep 17 00:00:00 2001 From: Nicholas Chammas Date: Sat, 22 Aug 2026 11:40:01 -0400 Subject: [PATCH 5/6] fix diff noise --- AGENTS.md | 21 ++++++--------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 062733c7ce970..57ec6dd3ee716 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,22 +5,13 @@ Before the first code edit or running test in a session, ensure a clean working environment. DO NOT skip these checks: -1. Run `git remote -v` to identify the personal fork and upstream (`apache/spark`). If unclear, - ask the user to configure their remotes following the standard convention (`origin` for the - fork, `upstream` for `apache/spark`). -2. If the latest commit on `/master` is more than a day old (check with - `git log -1 --format="%ci" /master`), run `git fetch master`. -3. If there are uncommitted changes (check with `git status`), ask the user to stash them before - proceeding. +1. Run `git remote -v` to identify the personal fork and upstream (`apache/spark`). If unclear, ask the user to configure their remotes following the standard convention (`origin` for the fork, `upstream` for `apache/spark`). +2. If the latest commit on `/master` is more than a day old (check with `git log -1 --format="%ci" /master`), run `git fetch master`. +3. If there are uncommitted changes (check with `git status`), ask the user to stash them before proceeding. 4. Switch to the appropriate branch: - - **Existing PR**: resolve the PR branch name via `gh api repos/apache/spark/pulls/ --jq - '.head.ref'`, then look for a local branch matching that name. If found, switch to it and - inform the user. If not found, ask whether to fetch it or if there is a local branch under a - different name. - - **New edits**: ask the user to choose: create a new git worktree from - `/master` with `--no-track` and work from there (recommended), or - create and switch to a new branch from `/master` with `--no-track`. - - **Running tests**: use `/master`. + - **Existing PR**: resolve the PR branch name via `gh api repos/apache/spark/pulls/ --jq '.head.ref'`, then look for a local branch matching that name. If found, switch to it and inform the user. If not found, ask whether to fetch it or if there is a local branch under a different name. + - **New edits**: ask the user to choose: create a new git worktree from `/master` with `--no-track` and work from there (recommended), or create and switch to a new branch from `/master`. + - **Running tests**: use `/master`. ## Development Notes From 01a9aa2a6cdb39d5848ca4300ee2496f62bc864d Mon Sep 17 00:00:00 2001 From: Nicholas Chammas Date: Sat, 22 Aug 2026 11:40:49 -0400 Subject: [PATCH 6/6] more noise --- AGENTS.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 57ec6dd3ee716..afbc5794b4186 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,15 +2,14 @@ ## Pre-flight Checks -Before the first code edit or running test in a session, ensure a clean working -environment. DO NOT skip these checks: +Before the first code edit or running test in a session, ensure a clean working environment. DO NOT skip these checks: 1. Run `git remote -v` to identify the personal fork and upstream (`apache/spark`). If unclear, ask the user to configure their remotes following the standard convention (`origin` for the fork, `upstream` for `apache/spark`). 2. If the latest commit on `/master` is more than a day old (check with `git log -1 --format="%ci" /master`), run `git fetch master`. 3. If there are uncommitted changes (check with `git status`), ask the user to stash them before proceeding. 4. Switch to the appropriate branch: - **Existing PR**: resolve the PR branch name via `gh api repos/apache/spark/pulls/ --jq '.head.ref'`, then look for a local branch matching that name. If found, switch to it and inform the user. If not found, ask whether to fetch it or if there is a local branch under a different name. - - **New edits**: ask the user to choose: create a new git worktree from `/master` with `--no-track` and work from there (recommended), or create and switch to a new branch from `/master`. + - **New edits**: ask the user to choose: create a new git worktree from `/master` with `--no-track` and work from there (recommended), or create and switch to a new branch from `/master` with `--no-track`. - **Running tests**: use `/master`. ## Development Notes