Two files, one repository
SeleniumHQ/selenium ships 1 format across 7 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 2 | 12 | 6 | 10% |
| Commands | 0 | 2 | 0 | 0% |
| Section tags | 2 | 3 | 1 | 33% |
What each file covers
Sections
2 shared · 12 only in A · 6 only in B- − Overview
- − Local contributor customization
- − Invariants (don't violate unless explicitly asked)
- − Toolchain
- − Execution model
- − Repo layout
- − Cross-binding consistency checks
- − Deprecation policy
- − General Guidelines
- − High risk changes (request verification before modifying unless explicitly instructed)
- − After making code changes
- − Reviewing pull requests
- + Code location
- + Common commands
- + Code conventions
- + Interfaces
- + Deprecation
- + Documentation
- Testing
- Logging
Commands
0 shared · 2 only in A · 0 only in B- − go.bat
- − dotnet/
Section tags
2 shared · 3 only in A · 1 only in B- − architecture
- − git-pr
- − do-not
- + docs
- test
- code-style
Line diff
SeleniumHQ/selenium · AGENTS.md
@@ −1 @@
1<!--
2Guidance for AI agents working in the Selenium monorepo.
3Language-specific details live in respective subdirectories.
4-->
5## Overview
6
7Selenium is a Bazel-built monorepo implementing the W3C WebDriver (and related) protocols,
8shipping multiple language bindings plus Grid and Selenium Manager.
9The repository README is aimed at contributors; end-user docs live elsewhere.
10
11### Local contributor customization
12- The `.local/` directory is available for customization, generated artifacts, scratch work, and temporary files. It is ignored by Git except for `.local/README.md`.
13- A contributor may create `.local/AGENTS.md` for personal repo-specific instructions and preferences. Before beginning any task, check whether `.local/AGENTS.md` exists; if it exists, read it with your file-reading tool and apply it as the contributor's local instruction overlay.
14- If `.local/agent/skills/` exists, inspect its `*/SKILL.md` files and treat them as additional user-defined skills.
15
16## Invariants (don't violate unless explicitly asked)
17- Maintain API/ABI compatibility by default (users upgrade by changing only the version number); public functionality may be removed only after it has gone through the [Deprecation policy](#deprecation-policy) below
18- Avoid repo-wide refactors/formatting; prefer small, reversible diffs
19
20## Toolchain
21- The project uses Bazelisk with a hermetic Bazel toolset. Do not run tests or execute Selenium code assuming a language-specific local development environment is configured.
22- Rakefile tasks are executed with a bundled jruby wrapped with `go`/`go.bat` and frequently used by CI jobs
23- Prefer targeted Bazel commands; use `bazel query ...` to locate labels before build/test
24
25## Execution model
26- Use `bazel query` to explore build graph before reading files
27- Attempt to execute Bazel commands directly. If prevented due to network/toolchain restrictions within the sandbox, fall back to suggesting copy/paste commands for the user on a separate line.
28- When the default output directory is restricted or when working in a git worktree, isolate build output with `--output_base`. It is a startup flag, so it goes *before* the command, and anchor it to the worktree root so it resolves the same from any directory: `bazel --output_base="$(git rev-parse --show-toplevel)/.local/output-base" build //...` (not after `build`/`test`/`query`).
29
30## Repo layout
31Bindings (see `AGENTS.md` in each directory for language-specific details):
32- Java: `java/`
33- Python: `py/`
34- Ruby: `rb/`
35- JavaScript: `javascript/selenium-webdriver/`
36- .NET: `dotnet/`
37
38Shared/high-risk areas:
39- `rust/` (Selenium Manager, see `rust/AGENTS.md`)
40- `common/` (build/test wiring; affects multiple areas)
41- `common/src/` (test HTML fixtures)
42- `javascript/atoms/` (shared JS atoms; high blast radius)
43- `scripts/`, `rake_tasks/`, `.github/`, `Rakefile` (tooling/build)
44- `third_party/` treat as read-only
45- `bazel-*/` treat as generated output
46
47## Cross-binding consistency checks
48When changing user-visible behavior, compare with at least one other binding:
49- Example: `rg <term> java/ py/ rb/ dotnet/ javascript/selenium-webdriver/`
50
51If behavior is shared/low-level (protocol, serialization, "remote"/transport), suggest follow-up parity work or to file an issue
52
53## Testing
54When implementing solutions prefer writing a test for it first
55Prefer small (unit) tests over browser tests for speed/reliability
56Avoid mocks—they can misrepresent API contracts
57
58Useful flags:
59- `--test_size_filters=small` (unit tests only)
60- `--test_output=all` (display console output)
61- `--cache_test_results=no` (force re-run)
62See language-specific AGENTS.md for applicable testing usage
63
64## Logging
65Add logging where users may need insight into what's happening
66See language-specific AGENTS.md for applicable logging usage
67
68## Deprecation policy
69This project does not follow semantic versioning (semver); before removing public functionality, mark it as deprecated with a message pointing to the alternative.
70See language-specific AGENTS.md for applicable deprecation usage
71
72## General Guidelines
73- Comments should explain *why*, not *what* - prefer well-named methods over comments
74- PRs should focus on one thing; we squash PRs to default `trunk` branch
75- Prefer copying files to deleting and recreating to maintain git history
76- Avoid running `bazel clean --expunge`
77- Formatting:
78 - `./scripts/format.sh` without arguments will run everything similar to running `./go format` but with failure information; With `--pre-commit` flag it only checks staged changes; With `--pre-push` flag it only checks committed changes with trunk.
79 - If `./scripts/format.sh` is already referenced in a pre-commit or pre-push hook, let the hooks handle formatting
80 - If not, run or suggest `./scripts/format.sh --pre-push` before pushing to avoid CI formatter failures
81
82## High risk changes (request verification before modifying unless explicitly instructed)
83- Everything referenced above as high risk
84- WebDriver/BiDi semantics, capability parsing, wire-level behavior
85- Dependency updates / `MODULE.bazel` / repin flows
86- Grid routing/distributor/queue logic
87
88## After making code changes
89- Call out any high risk areas touched
90- Note cross-binding impact and any follow-up issues needed
91
92## Reviewing pull requests
93See `.github/pr_review.md` for agentic review priorities and scope.
94
SeleniumHQ/selenium · java/AGENTS.md
@@ +1 @@
1<!-- Guidance for AI agents working in Selenium Java Bindings and Grid. -->
2
3## Code location
4- Java Bindings: `java/src/`, `java/test/`
5- Grid Server: `java/src/org/openqa/selenium/grid/`
6
7## Common commands
8- Build: `bazel build //java/...`
9- Build Grid: `bazel build grid`
10
11## Testing
12See `java/TESTING.md`
13
14## Code conventions
15### Interfaces
16- New methods added to existing interfaces must provide a default implementation, if possible.
17- Interfaces must not expose the native classes of their implementations.
18
19### Logging
20```java
21import java.util.logging.Logger;
22private static final Logger LOG = Logger.getLogger(MyClass.class.getName());
23
24LOG.warning("actionable: something needs attention");
25LOG.info("useful: server started on port 4444");
26LOG.fine("diagnostic: request details for debugging");
27```
28
29### Deprecation
30```java
31@Deprecated(forRemoval = true)
32public void legacyMethod() { }
33```
34
35### Documentation
36Use Javadoc for public APIs:
37```java
38/**
39 * Brief description.
40 *
41 * @param name description
42 * @return description
43 * @throws ExceptionType when condition
44 */
45```
46
@@ −1 +1 @@
1−<!--
2−Guidance for AI agents working in the Selenium monorepo.
3−Language-specific details live in respective subdirectories.
4−-->
5−## Overview
1+<!-- Guidance for AI agents working in Selenium Java Bindings and Grid. -->
62
7−Selenium is a Bazel-built monorepo implementing the W3C WebDriver (and related) protocols,
8−shipping multiple language bindings plus Grid and Selenium Manager.
9−The repository README is aimed at contributors; end-user docs live elsewhere.
3+## Code location
4+- Java Bindings: `java/src/`, `java/test/`
5+- Grid Server: `java/src/org/openqa/selenium/grid/`
106
11−### Local contributor customization
12−- The `.local/` directory is available for customization, generated artifacts, scratch work, and temporary files. It is ignored by Git except for `.local/README.md`.
13−- A contributor may create `.local/AGENTS.md` for personal repo-specific instructions and preferences. Before beginning any task, check whether `.local/AGENTS.md` exists; if it exists, read it with your file-reading tool and apply it as the contributor's local instruction overlay.
14−- If `.local/agent/skills/` exists, inspect its `*/SKILL.md` files and treat them as additional user-defined skills.
7+## Common commands
8+- Build: `bazel build //java/...`
9+- Build Grid: `bazel build grid`
1510
16−## Invariants (don't violate unless explicitly asked)
17−- Maintain API/ABI compatibility by default (users upgrade by changing only the version number); public functionality may be removed only after it has gone through the [Deprecation policy](#deprecation-policy) below
18−- Avoid repo-wide refactors/formatting; prefer small, reversible diffs
19−
20−## Toolchain
21−- The project uses Bazelisk with a hermetic Bazel toolset. Do not run tests or execute Selenium code assuming a language-specific local development environment is configured.
22−- Rakefile tasks are executed with a bundled jruby wrapped with `go`/`go.bat` and frequently used by CI jobs
23−- Prefer targeted Bazel commands; use `bazel query ...` to locate labels before build/test
24−
25−## Execution model
26−- Use `bazel query` to explore build graph before reading files
27−- Attempt to execute Bazel commands directly. If prevented due to network/toolchain restrictions within the sandbox, fall back to suggesting copy/paste commands for the user on a separate line.
28−- When the default output directory is restricted or when working in a git worktree, isolate build output with `--output_base`. It is a startup flag, so it goes *before* the command, and anchor it to the worktree root so it resolves the same from any directory: `bazel --output_base="$(git rev-parse --show-toplevel)/.local/output-base" build //...` (not after `build`/`test`/`query`).
29−
30−## Repo layout
31−Bindings (see `AGENTS.md` in each directory for language-specific details):
32−- Java: `java/`
33−- Python: `py/`
34−- Ruby: `rb/`
35−- JavaScript: `javascript/selenium-webdriver/`
36−- .NET: `dotnet/`
37−
38−Shared/high-risk areas:
39−- `rust/` (Selenium Manager, see `rust/AGENTS.md`)
40−- `common/` (build/test wiring; affects multiple areas)
41−- `common/src/` (test HTML fixtures)
42−- `javascript/atoms/` (shared JS atoms; high blast radius)
43−- `scripts/`, `rake_tasks/`, `.github/`, `Rakefile` (tooling/build)
44−- `third_party/` treat as read-only
45−- `bazel-*/` treat as generated output
46−
47−## Cross-binding consistency checks
48−When changing user-visible behavior, compare with at least one other binding:
49−- Example: `rg <term> java/ py/ rb/ dotnet/ javascript/selenium-webdriver/`
50−
51−If behavior is shared/low-level (protocol, serialization, "remote"/transport), suggest follow-up parity work or to file an issue
52−
5311 ## Testing
54−When implementing solutions prefer writing a test for it first
55−Prefer small (unit) tests over browser tests for speed/reliability
56−Avoid mocks—they can misrepresent API contracts
12+See `java/TESTING.md`
5713
58−Useful flags:
59−- `--test_size_filters=small` (unit tests only)
60−- `--test_output=all` (display console output)
61−- `--cache_test_results=no` (force re-run)
62−See language-specific AGENTS.md for applicable testing usage
14+## Code conventions
15+### Interfaces
16+- New methods added to existing interfaces must provide a default implementation, if possible.
17+- Interfaces must not expose the native classes of their implementations.
6318
64−## Logging
65−Add logging where users may need insight into what's happening
66−See language-specific AGENTS.md for applicable logging usage
19+### Logging
20+```java
21+import java.util.logging.Logger;
22+private static final Logger LOG = Logger.getLogger(MyClass.class.getName());
6723
68−## Deprecation policy
69−This project does not follow semantic versioning (semver); before removing public functionality, mark it as deprecated with a message pointing to the alternative.
70−See language-specific AGENTS.md for applicable deprecation usage
24+LOG.warning("actionable: something needs attention");
25+LOG.info("useful: server started on port 4444");
26+LOG.fine("diagnostic: request details for debugging");
27+```
7128
72−## General Guidelines
73−- Comments should explain *why*, not *what* - prefer well-named methods over comments
74−- PRs should focus on one thing; we squash PRs to default `trunk` branch
75−- Prefer copying files to deleting and recreating to maintain git history
76−- Avoid running `bazel clean --expunge`
77−- Formatting:
78− - `./scripts/format.sh` without arguments will run everything similar to running `./go format` but with failure information; With `--pre-commit` flag it only checks staged changes; With `--pre-push` flag it only checks committed changes with trunk.
79− - If `./scripts/format.sh` is already referenced in a pre-commit or pre-push hook, let the hooks handle formatting
80− - If not, run or suggest `./scripts/format.sh --pre-push` before pushing to avoid CI formatter failures
29+### Deprecation
30+```java
31+@Deprecated(forRemoval = true)
32+public void legacyMethod() { }
33+```
8134
82−## High risk changes (request verification before modifying unless explicitly instructed)
83−- Everything referenced above as high risk
84−- WebDriver/BiDi semantics, capability parsing, wire-level behavior
85−- Dependency updates / `MODULE.bazel` / repin flows
86−- Grid routing/distributor/queue logic
87−
88−## After making code changes
89−- Call out any high risk areas touched
90−- Note cross-binding impact and any follow-up issues needed
91−
92−## Reviewing pull requests
93−See `.github/pr_review.md` for agentic review priorities and scope.
35+### Documentation
36+Use Javadoc for public APIs:
37+```java
38+/**
39+ * Brief description.
40+ *
41+ * @param name description
42+ * @return description
43+ * @throws ExceptionType when condition
44+ */
45+```
9446
