You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d5a0bc2
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: AGENTS.md
+7-5Lines changed: 7 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -80,8 +80,9 @@ No check can enforce these, so each one names the mistake it prevents.
80
80
changes what an app's schema build does, and the unit tests don't build through the public API alone. Failure: an agent
81
81
skipped the probe on a scanner rewrite because it was a refactor.
82
82
-**Keep a comment only for a non-obvious why.** No comment that repeats the code, narrates history, or carries an issue or
83
-
PR number outside a TODO. Failure: a comment explained what `determineType` returned, which the `namedType` default
84
-
already showed, and a follow-up commit deleted it (`7448f2c6`).
83
+
PR number outside a TODO. `CommentConventionsTest` catches issue numbers and the history phrases it lists. A comment that
84
+
repeats the code, or tells history in other words, gets past it. Failure: a comment explained what `determineType`
85
+
returned, which the `namedType` default already showed, and a follow-up commit deleted it (`7448f2c6`).
85
86
86
87
## Rule table
87
88
@@ -95,7 +96,7 @@ happening. "docs only" means nothing does yet, so the rule depends on you readin
95
96
| A resolver method's parameter layout, type variables and source are decided once, at schema build | docs only |
96
97
| A change to how resolvers are found, bound or unwrapped keeps what a method, a property and a Map field return |`ResolverCompatibilityTest`, which compares field and Map values with a method's, and the bounded check in `ReturnValueUnwrappingTest`, which compares all three with the plain value. Neither has known findings, so a value that differs on a return type they run fails the build. The bounded check also pins how many return types it generates, and for each kind how many the build rejects and how many executions run, so a change that stops running some fails until the same diff updates `pinnedCoverage`. It doesn't judge whether a newly rejected return type should build |
97
98
| One output has one builder. Don't add a second path that builds the same thing | docs only |
98
-
| Read an SDL type's members merged with its extensions, never from the raw definition |`MergedType` in `MergedDefinitions.kt` and `DefinitionsBoundaryTest`, which fails on a raw member, directive or child-node read, an extension class, an SDL node walk or a `TypeDefinitionRegistry` call outside it. A read by reflection gets past it |
99
+
| Read an SDL type's members merged with its extensions, never from the raw definition |`MergedType` in `MergedDefinitions.kt` and `DefinitionsBoundaryTest`, which fails on a raw member, directive or child-node read, an extension class, an SDL node walk or a `TypeDefinitionRegistry` call outside it. A read by reflection gets past it. `TypeExtensionTest` builds and queries a schema with an extension of every kind, so a build that leaves an extension's fields, interfaces, members, values, input fields or directives out of the built type fails it, however the code read them|
99
100
| Every kind of SDL type starts its graphql-java type from the same recipe |`MergedType.prepare`, `DefinitionsBoundaryTest` and `TypeKindRecipeTest`|
100
101
| Reuse an existing structure before you add a parallel one | docs only |
101
102
| Argument conversion goes through one entry point | docs only |
@@ -111,16 +112,17 @@ happening. "docs only" means nothing does yet, so the rule depends on you readin
111
112
| Directive wirings decide which types become `GraphQLTypeReference` in one place |`TypeReferences` in `DirectiveWiringHelper`|
112
113
| An object built once at schema build holds no per-request state | docs only |
113
114
| Add a variant to the existing test class and its shared fixtures | docs only |
115
+
| Every test class in `src/test` runs, and so do its assertions | surefire's `**/*` include, so a class runs whatever its name, and `failIfNoTests`, which fails a run that executes no tests. The Kotlin test compile's `-Xassertions=always-enable` makes `assert()`, which `TestUtils.assertEquals` uses, run without `-ea`. `-DfailIfNoTests=false` turns the empty-run check off, and a test that asserts nothing still passes |
114
116
| A new test fails without the change it guards | docs only |
115
117
| A fix keeps every shape that worked on the last release | docs only |
116
118
| A test that builds a schema also queries its fields with `assertEveryFieldResolves`| docs only |
117
-
| The first commit of a fix tests the neighbouring shapes, not just the reported one |docs only |
119
+
| The first commit of a fix tests the neighbouring shapes, not just the reported one |For return values, the bounded check in `ReturnValueUnwrappingTest` at `mvn verify`, which builds every nesting of up to 3 containers around each leaf type, for methods, properties and Map fields. Docs only for other shapes|
118
120
| The build passes on JDK 17, the lowest supported version | CI on JDK 17, 21 and 25 |
119
121
| Run verify-tools before you push a schema-building change | docs only |
120
122
| The packaged jar holds `module-info.class`, its non-static `requires` resolve from the runtime dependencies, and every class targets the pom's `java.version`|`build/JarCheck.java` at `mvn verify`|
121
123
| Compiler warnings fail the build |`-Werror` and `failOnWarning` in `pom.xml`|
122
124
| Check every claim in a PR body or release note at the current head | docs only |
123
-
| Keep a comment only for a non-obvious why, with no history and no issue numbers outside a TODO | docs only |
125
+
| Keep a comment only for a non-obvious why, with no history and no issue numbers outside a TODO |`CommentConventionsTest`, which reads each comment block in the `.kt` and `.java` files under `src/main` and `src/test` and fails on an issue number or issue link outside `// TODO <change> in X.0.0 (#N)`, a history phrase from its list, or a version such as `@since` or "since 1.2.0". `lint-allow <rule> until YYYY-MM-DD by <name>: <reason>` on the line skips that rule there, for at most 90 days. History in words the list doesn't have, and a comment that repeats the code, are docs only |
124
126
| Build only what was asked | docs only |
125
127
| A build you trust starts from an empty `target/`, so no class from an earlier build ships |`clean` in `probe.sh install`, docs only for your own `mvn` runs |
126
128
| Agent worktrees and local settings stay out of commits |`.gitignore`|
0 commit comments