From 682ea51764bc399e39b7b784c35e493596742cb9 Mon Sep 17 00:00:00 2001 From: Alan Agius <17563226+alan-agius4@users.noreply.github.com> Date: Mon, 28 Sep 2026 11:47:35 +0000 Subject: [PATCH 1/2] docs: expand coding, testing, and PR guidelines in AGENTS.md Updates `AGENTS.md` with additional guidance for AI agents: - Adds a `Coding Practices` section covering imports (including `import type`) and preferring ECMAScript private fields (`#field`). - Documents how to run unit tests without sharding and retries using `--config=no-sharding`. - Clarifies that fixup commits should only be used for changes belonging to the target commit, while unrelated changes must use a separate commit. --- AGENTS.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a8b5b9fca54f..1c6eed5e6671 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,15 @@ This is the source code for the Angular CLI and related build tooling. This guid pnpm build --local ``` +## Coding Practices + +- **Imports:** + - Always use the `node:` protocol for Node.js built-in imports (e.g., `node:fs`, `node:path`, `node:assert`). + - Prefer named imports (e.g., `import { mkdtemp } from 'node:fs'`) or default imports (`import fs from 'node:fs'`) instead of namespace imports (`import * as fs`). + - Use type-only imports (`import type { ... }`) when importing types to avoid runtime side-effects. +- **Classes:** + - Prefer ECMAScript private fields (`#field`) over TypeScript `private` keywords for encapsulated state. + ## Testing - **Temporary Directories (`TEST_TMPDIR`):** @@ -42,14 +51,14 @@ This is the source code for the Angular CLI and related build tooling. This guid }); ``` - **NEVER** use or fallback to `os.tmpdir()`. Bazel executes tests in hermetic sandboxes and sets `TEST_TMPDIR` to an isolated, sandboxed directory. Using `os.tmpdir()` can cause sandboxing failures, permission errors, or file leakage outside the Bazel sandbox. -- **Imports:** - - Always use the `node:` protocol for Node.js built-in imports (e.g., `node:fs`, `node:path`, `node:assert`). - - Prefer named imports (e.g., `import { mkdtemp } from 'node:fs'`) or default imports (`import fs from 'node:fs'`) instead of namespace imports (`import * as fs`). - **Unit Tests:** - Run all unit tests: `pnpm bazel test //packages/...` - Run a specific test target: `pnpm bazel test //packages/angular/build:test` - Query test targets: `pnpm bazel query "tests(//packages/...)"` - Focus specific tests when debugging: use `fdescribe()` and `fit()`. NEVER commit focused tests to the repository. + - Run tests without sharding: use `--config=no-sharding` (e.g., `pnpm bazel test //packages/angular/build:test --config=no-sharding`). + This disables test sharding (`--test_sharding_strategy=disabled`) and flaky test retries (`--flaky_test_attempts=1`). + This is especially useful when isolating test runs or debugging with focused tests (`fit`/`fdescribe`) to avoid empty shard failures and unnecessary re-runs. - **End-to-End Tests:** - Run subset of E2E tests: `pnpm bazel test //tests:e2e_node22 --config=e2e --test_filter=""` @@ -58,6 +67,7 @@ This is the source code for the Angular CLI and related build tooling. This guid - Use the `gh` CLI (GitHub CLI) for creating and managing pull requests. - **Fixup Commits:** - When addressing review feedback, **ALWAYS** use fixup commits (`git commit --fixup `) instead of amending existing commits. This preserves commit history during review and allows reviewers to easily see incremental changes. + - Only use fixup commits for changes that directly belong to the target commit. Unrelated changes must be made in a separate commit with their own commit message, not as a fixup commit. - Fixup commits are automatically squashed when merging with `pnpm ng-dev pr merge` or rebasing with `pnpm ng-dev pr rebase `. - Use `pnpm ng-dev pr` commands: - `pnpm ng-dev pr rebase `: Rebase a PR branch on its target branch and squash fixup commits. From f2564c3cadf6f62077f4e7c6433995a629418587 Mon Sep 17 00:00:00 2001 From: Alan Agius <17563226+alan-agius4@users.noreply.github.com> Date: Mon, 28 Sep 2026 16:15:53 +0000 Subject: [PATCH 2/2] fixup! docs: expand coding, testing, and PR guidelines in AGENTS.md --- AGENTS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 1c6eed5e6671..b7b2e48797e1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,9 +56,10 @@ This is the source code for the Angular CLI and related build tooling. This guid - Run a specific test target: `pnpm bazel test //packages/angular/build:test` - Query test targets: `pnpm bazel query "tests(//packages/...)"` - Focus specific tests when debugging: use `fdescribe()` and `fit()`. NEVER commit focused tests to the repository. - - Run tests without sharding: use `--config=no-sharding` (e.g., `pnpm bazel test //packages/angular/build:test --config=no-sharding`). + - Run tests without sharding when isolating or debugging: use `--config=no-sharding` with a specific test target (e.g., `pnpm bazel test //packages/angular/build:test --config=no-sharding`). This disables test sharding (`--test_sharding_strategy=disabled`) and flaky test retries (`--flaky_test_attempts=1`). This is especially useful when isolating test runs or debugging with focused tests (`fit`/`fdescribe`) to avoid empty shard failures and unnecessary re-runs. + Do not use this flag when running broad test suites (such as `//packages/...`), as executing tests without sharding takes significantly longer. - **End-to-End Tests:** - Run subset of E2E tests: `pnpm bazel test //tests:e2e_node22 --config=e2e --test_filter=""`