Create sub-team and investigate pre-merge testing for branches used for PRs

[jbphet]

This came out of the 5/21/2026 developer meeting. Several people are expressing interest in working on the sub-team.

[jbphet]

@marlitas is interested in working on GitHub actions, but doesn't want to lead the team.

@AgustinVallejo has some experience with GitHub actions also.

@samreid had proposed the test efficiency topic for dev meeting that kicked off this discussion.

@zepumph has knowledge and experience based on what the website team has done in this realm.

[jbphet]

Related pre-existing related issues:

https://github.com/phetsims/aqua/issues/216
https://github.com/phetsims/totality/issues/104
phetsims/tasks#1086

[jbphet]

@marlitas will take this to planning to help figure out who should lead this effort and when we can work on it.

[samreid]

Ideas from today's meeting:

Details

• I’d use the targets like this:

• During normal work:
  npm run check -- --target=working-copy --fix --skip-phet-io-compare-api
• Before opening/updating a PR, especially after rebase:
  npm run check -- --target=branch --base=origin/main
• Before direct-pushing to your upstream branch/main:
  npm run check -- --target=unpushed
• In a pre-commit hook, if kept:
  npm run check -- --target=staged

For GitHub Actions, I’d start with one required workflow on PRs and main pushes:

  name: check

  on:
    pull_request:
      branches: [ main ]
    push:
      branches: [ main ]
    merge_group:
    workflow_dispatch:

  jobs:
    check:
      runs-on: ubuntu-latest
      timeout-minutes: 30

      steps:
        - uses: actions/checkout@v6
          with:
            fetch-depth: 0

        - uses: actions/setup-node@v6
          with:
            node-version: 24
            cache: npm

        - run: npm ci

        - name: Check PR branch
          if: github.event_name == 'pull_request'
          run: npm run check -- --target=branch --base=origin/${{ github.base_ref }} 

        - name: Check merge queue / main
          if: github.event_name != 'pull_request'
          run: npm run check -- --target=working-copy 

• fetch-depth: 0 matters because --target=branch --base=origin/main needs enough git history to compute the merge-base.
• Include merge_group if you use GitHub merge queue; GitHub documents that required checks need that trigger for merge queue.
• Do not use --fix in CI unless you intentionally want an auto-commit bot. CI should fail and tell the developer to run --fix locally.
• For a required PR check, avoid path filters at first. GitHub warns skipped required workflows can remain pending.

Subject: [PATCH] Reduce wave amplitude downstream of the slits, see https://github.com/phetsims/quantum-wave-interference/issues/152
---
Index: _totality/scripts/check.mts
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/_totality/scripts/check.mts b/_totality/scripts/check.mts
--- a/_totality/scripts/check.mts	(revision 340b2e7ac44533d872f5d1d6ace55b14197d1f00)
+++ b/_totality/scripts/check.mts	(date 1779990344720)
@@ -11,7 +11,12 @@
  *   npm run check -- --type-check               # type-check only
  *   npm run check -- --report-media             # report-media only
  *   npm run check -- --fix                      # apply any automated auto-fixes (currently lint)
- *   npm run check -- --pre-commit               # only check staged files (for git hooks)
+ *   npm run check -- --target=working-copy      # check staged and unstaged files (default)
+ *   npm run check -- --target=staged            # check staged files only
+ *   npm run check -- --target=branch            # check files changed since --base, default origin/main
+ *   npm run check -- --target=unpushed          # check committed files ahead of the branch upstream
+ *   npm run check -- --base=origin/main         # base ref for --target=branch
+ *   npm run check -- --pre-commit               # alias for --target=staged (for git hooks)
  *   npm run check -- --absolute                 # output absolute paths (for IDE hyperlinking)
  *   npm run check -- --dirs=<a,b,c>             # only check these directories (comma-separated)
  *   npm run check -- --list-type-check-dirs     # print computed type-check dirs and exit
@@ -42,6 +47,9 @@
 
 const TOTALITY_DIR = '_totality';
 const SCAN_EXCLUDED_DIRS = new Set( [ 'build', 'dist', 'node_modules', '.git', '.scenerystack' ] );
+const CHANGE_TARGETS = [ 'working-copy', 'staged', 'branch', 'unpushed' ] as const;
+
+type ChangeTarget = typeof CHANGE_TARGETS[ number ];
 
 /**
  * Convert historical/polyrepo naming to the directory name used in this monorepo.
@@ -52,6 +60,116 @@
   return repo === 'perennial' ? 'perennial-alias' : repo;
 }
 
+/**
+ * Parse a single command line option value, exiting on duplicate options.
+ * @param optionName - option name without leading "--"
+ * @returns option value, or null if omitted
+ */
+function getOptionValue( optionName: string ): string | null {
+  const prefix = `--${optionName}=`;
+  const optionValues = args.filter( arg => arg.startsWith( prefix ) ).map( arg => arg.slice( prefix.length ) );
+  if ( optionValues.length > 1 ) {
+    log( `Error: expected only one --${optionName}= option.` );
+    process.exit( 1 );
+  }
+
+  return optionValues[ 0 ] ?? null;
+}
+
+/**
+ * Normalize supported --target values and legacy aliases.
+ * @param rawTarget - user-provided --target value
+ * @returns normalized change target
+ */
+function normalizeChangeTarget( rawTarget: string ): ChangeTarget {
+  const changeTarget = rawTarget === 'workingcopychanges' ? 'working-copy' :
+                       rawTarget === 'unpushedchanges'   ? 'unpushed' :
+                       rawTarget;
+
+  if ( CHANGE_TARGETS.includes( changeTarget as ChangeTarget ) ) {
+    return changeTarget as ChangeTarget;
+  }
+
+  log( `Error: unsupported --target=${rawTarget}. Supported targets: ${CHANGE_TARGETS.join( ', ' )}` );
+  process.exit( 1 );
+}
+
+/**
+ * Split git diff output into non-empty file paths.
+ * @param stdout - git stdout
+ * @returns file paths
+ */
+function splitGitFiles( stdout: string ): string[] {
+  return stdout.trim().split( '\n' ).filter( Boolean );
+}
+
+/**
+ * Get staged and unstaged file changes.
+ * @returns changed file paths
+ */
+async function getWorkingCopyChangedFiles(): Promise<string[]> {
+  const [ unstaged, staged ] = await Promise.all( [
+    run( 'git', [ 'diff', '--name-only' ] ),
+    run( 'git', [ 'diff', '--name-only', '--cached' ] )
+  ] );
+
+  return [ ...splitGitFiles( unstaged.stdout ), ...splitGitFiles( staged.stdout ) ];
+}
+
+/**
+ * Get staged file changes.
+ * @returns changed file paths
+ */
+async function getStagedChangedFiles(): Promise<string[]> {
+  const staged = await run( 'git', [ 'diff', '--name-only', '--cached' ] );
+  return splitGitFiles( staged.stdout );
+}
+
+/**
+ * Get files changed on the current branch relative to a base ref.
+ * @param baseRef - base git ref
+ * @returns changed file paths
+ */
+async function getBranchChangedFiles( baseRef: string ): Promise<string[]> {
+  try {
+    const branch = await run( 'git', [ 'diff', '--name-only', `${baseRef}...HEAD` ] );
+    return splitGitFiles( branch.stdout );
+  }
+  catch( error ) {
+    log( `Error: --target=branch could not diff against --base=${baseRef}.` );
+    throw error;
+  }
+}
+
+/**
+ * Get committed files that are ahead of the current branch upstream.
+ * @returns changed file paths
+ */
+async function getUnpushedChangedFiles(): Promise<string[]> {
+  try {
+    const unpushed = await run( 'git', [ 'diff', '--name-only', '@{upstream}..HEAD' ] );
+    return splitGitFiles( unpushed.stdout );
+  }
+  catch( error ) {
+    log( 'Error: --target=unpushed requires the current branch to have an upstream.' );
+    throw error;
+  }
+}
+
+/**
+ * Get changed files from the selected target.
+ * @param changeTarget - source of changes to inspect
+ * @param baseRef - base ref used by --target=branch
+ * @returns changed file paths
+ */
+async function getChangedFiles( changeTarget: ChangeTarget, baseRef: string ): Promise<string[]> {
+  return changeTarget === 'working-copy' ? getWorkingCopyChangedFiles() :
+         changeTarget === 'staged'       ? getStagedChangedFiles() :
+         changeTarget === 'branch'       ? getBranchChangedFiles( baseRef ) :
+         changeTarget === 'unpushed'     ? getUnpushedChangedFiles() :
+         ( () => { throw new Error( `Unrecognized changeTarget: ${changeTarget}` ); } )();
+}
+
 function formatQUnitResult( result: QUnitResult ): string[] {
   const lines: string[] = [];
   const tests = result.tests;
@@ -467,11 +585,25 @@
   .filter( Boolean );
 verifyExplicitDirs( explicitDirs );
 
-// In --pre-commit mode, only look at staged changes (the unstaged diff is irrelevant
-// during a git hook because it contains changes deliberately left out of the commit).
-// Also ignores lint auto-fix, since fixes would modify the working tree but not the
-// staged snapshot, leaving the commit with unfixed code and surprise unstaged changes.
 const preCommit = hasFlag( 'pre-commit' );
+const targetArg = getOptionValue( 'target' );
+const baseRef = getOptionValue( 'base' ) ?? 'origin/main';
+
+if ( preCommit && targetArg !== null && normalizeChangeTarget( targetArg ) !== 'staged' ) {
+  log( 'Error: --pre-commit is an alias for --target=staged and cannot be combined with another target.' );
+  process.exit( 1 );
+}
+
+const changeTarget = preCommit ? 'staged' : normalizeChangeTarget( targetArg ?? 'working-copy' );
+if ( changeTarget !== 'branch' && getOptionValue( 'base' ) !== null ) {
+  log( 'Error: --base is only supported with --target=branch.' );
+  process.exit( 1 );
+}
+
+// In staged mode, only look at staged changes (the unstaged diff is irrelevant during a git hook
+// because it contains changes deliberately left out of the commit). Also ignore lint auto-fix,
+// since fixes would modify the working tree but not the staged snapshot.
+const stagedOnly = changeTarget === 'staged';
 
 // If any task flag is specified, run only those tasks. Otherwise run all.
 const taskFlagsSpecified = hasFlag( 'lint' ) || hasFlag( 'type-check' ) || hasFlag( 'report-media' );
@@ -480,29 +612,17 @@
 const runReportMedia = taskFlagsSpecified ? hasFlag( 'report-media' ) : true;
 
 // Opt-out, not opt-in: run unless explicitly skipped, and suppress when any task flag above is
-// specified. Unit tests are additionally skipped in --pre-commit mode (puppeteer launch is too
-// slow for a blocking git hook); override with an explicit re-run via `npm run check` post-commit.
-const runUnitTest = !taskFlagsSpecified && !hasFlag( 'skip-unit-tests' ) && !preCommit;
+// specified. Unit tests are additionally skipped in staged mode (puppeteer launch is too slow
+// for a blocking git hook); override with an explicit re-run via `npm run check` post-commit.
+const runUnitTest = !taskFlagsSpecified && !hasFlag( 'skip-unit-tests' ) && !stagedOnly;
 const runPhetioApi = !taskFlagsSpecified && !hasFlag( 'skip-phet-io-compare-api' );
-const lintFix = hasFlag( 'fix' ) && !preCommit;
+const lintFix = hasFlag( 'fix' ) && !stagedOnly;
 const absolutePaths = hasFlag( 'absolute' );
 const listTypeCheckDirs = hasFlag( 'list-type-check-dirs' ) || hasFlag( 'dry-run' );
 
 const start = Date.now();
 
-let changedFiles;
-if ( preCommit ) {
-  const staged = await run( 'git', [ 'diff', '--name-only', '--cached' ] );
-  changedFiles = staged.stdout.trim().split( '\n' ).filter( Boolean );
-}
-else {
-  const [ unstaged, staged ] = await Promise.all( [
-    run( 'git', [ 'diff', '--name-only' ] ),
-    run( 'git', [ 'diff', '--name-only', '--cached' ] )
-  ] );
-  changedFiles = [ ...unstaged.stdout.trim().split( '\n' ), ...staged.stdout.trim().split( '\n' ) ]
-    .filter( Boolean );
-}
+const changedFiles = await getChangedFiles( changeTarget, baseRef );
 
 // Extract unique top-level directories
 const changedDirs = [ ...new Set( changedFiles.map( f => f.split( '/' )[ 0 ] ) ) ].sort();
@@ -527,7 +647,7 @@
     log( 'No matching repos for --dirs — nothing to check.' );
   }
   else {
-    log( 'No repos with changes — nothing to check.' );
+    log( `No repos with changes for target "${changeTarget}" — nothing to check.` );
   }
   process.exit( 0 );
 }
@@ -536,7 +656,8 @@
   log( `Requested repos: ${repos.join( ', ' )}` );
 }
 else {
-  log( `Changed repos: ${repos.join( ', ' )}` );
+  const targetLabel = changeTarget === 'branch' ? `${changeTarget} from ${baseRef}` : changeTarget;
+  log( `Changed repos (${targetLabel}): ${repos.join( ', ' )}` );
 }
 
 const failures: string[] = [];