From 45fa599092b960bc9ff0536bc9f3e32e2624ab4a Mon Sep 17 00:00:00 2001 From: Nicole Lee Date: Thu, 23 Jul 2026 19:39:21 +0000 Subject: [PATCH 1/2] feat: add JSpecify nullness guidelines to AGENTS.md --- AGENTS.md | 24 +++++++++++++++++++++--- 1 file changed, 21 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5a2b74edfeb6..86b93c3c716e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,16 +45,34 @@ This is a standard Maven project. 4. Avoid unnecessary formatting changes to keep diffs clean. 5. Use `mvn` for everything other than the `test/integration` folder. -## 5. Dependency Management +## 5. JSpecify Nullness Guidelines +To enforce compile-time null-safety and eliminate NullPointerExceptions, this repository is adopting JSpecify 1.0 annotations. + +### 5.1 Dependency Requirement +Before adding nullability annotations to any module, you must ensure the JSpecify dependency is declared in the module's `pom.xml` + +### 5.2 Handwritten vs. Generated Code Handling +- **Handwritten Modules**: Annotations are added to source files directly. +- **Generated Modules**: Do not edit generated class files manually! Instead, update the code generator engine (`gapic-generator-java`) to automatically produce the annotations during the generation phase. + +### 5.3 Annotation Usage & Type-Use Semantics +Prefer JSpecify annotations (`org.jspecify.annotations.NullMarked` and `org.jspecify.annotations.Nullable`) over legacy declaration annotations (like `javax.annotation.Nullable`). +- **Default semantics**: Annotate classes with `@NullMarked` to declare that all unannotated types exclude null. +- **Type-Use Placement Rules**: JSpecify annotations are type-use annotations. They must be placed in the type-use position: + - **Generics**: `List<@Nullable String> list` (non-null list containing nullable String elements). + - **Arrays**: `String @Nullable [] array` (nullable reference to an array). + - **Fully-Qualified**: `com.google.auth.oauth2.@Nullable TokenVerifier` (place immediately before the simple class name). + +## 6. Dependency Management - Do not bump external dependency versions unless for CVE or critical bug fix. - Avoid introducing new external dependencies if possible. Prefer Java standard library, then opt for existing dependencies. -## 6. Contribution Guidelines +## 7. Contribution Guidelines - **Commits**: Conventional Commits `(): `. - **Pull Requests**: Submitted via PR, require review. Pull latest from main and resolve conflicts. - **Testing**: All new logic should be accompanied by tests. -## 7. Specialized Development Guides +## 8. Specialized Development Guides For development on core components, refer to the following guides in `sdk-platform-java`: - **GAPIC Generator**: [sdk-platform-java/gapic-generator-java/DEVELOPMENT.md](sdk-platform-java/gapic-generator-java/DEVELOPMENT.md) - **GAX**: [sdk-platform-java/gax-java/DEVELOPMENT.md](sdk-platform-java/gax-java/DEVELOPMENT.md) From a7e54dc09ae2bfc19881072b8b8c6d47b5c976e6 Mon Sep 17 00:00:00 2001 From: Nicole Lee Date: Thu, 23 Jul 2026 21:39:24 +0000 Subject: [PATCH 2/2] updated context as per comments --- AGENTS.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 86b93c3c716e..1952fbdae22c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,23 +45,17 @@ This is a standard Maven project. 4. Avoid unnecessary formatting changes to keep diffs clean. 5. Use `mvn` for everything other than the `test/integration` folder. -## 5. JSpecify Nullness Guidelines -To enforce compile-time null-safety and eliminate NullPointerExceptions, this repository is adopting JSpecify 1.0 annotations. +## 5. Nullness Annotation Guidelines +To enforce compile-time null-safety and eliminate NullPointerExceptions, this repository is adopting JSpecify annotations. -### 5.1 Dependency Requirement -Before adding nullability annotations to any module, you must ensure the JSpecify dependency is declared in the module's `pom.xml` - -### 5.2 Handwritten vs. Generated Code Handling +### 5.1 Handwritten vs. Generated Code Handling - **Handwritten Modules**: Annotations are added to source files directly. - **Generated Modules**: Do not edit generated class files manually! Instead, update the code generator engine (`gapic-generator-java`) to automatically produce the annotations during the generation phase. -### 5.3 Annotation Usage & Type-Use Semantics +### 5.2 Annotation Usage & Type-Use Semantics Prefer JSpecify annotations (`org.jspecify.annotations.NullMarked` and `org.jspecify.annotations.Nullable`) over legacy declaration annotations (like `javax.annotation.Nullable`). - **Default semantics**: Annotate classes with `@NullMarked` to declare that all unannotated types exclude null. -- **Type-Use Placement Rules**: JSpecify annotations are type-use annotations. They must be placed in the type-use position: - - **Generics**: `List<@Nullable String> list` (non-null list containing nullable String elements). - - **Arrays**: `String @Nullable [] array` (nullable reference to an array). - - **Fully-Qualified**: `com.google.auth.oauth2.@Nullable TokenVerifier` (place immediately before the simple class name). +- **Nullable types**: Annotate fields, return types, or parameters with `@Nullable` if they are allowed to be null. ## 6. Dependency Management - Do not bump external dependency versions unless for CVE or critical bug fix.