Skip to content

Add comprehensive JSpecify @NullMarked annotations to remaining classes #262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Copilot wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Add comprehensive JSpecify @NullMarked annotations to remaining classes #262

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5bc117e
Initial plan
Copilot Jan 28, 2026
11e22a9
Add comprehensive JSpecify migration plan document
Copilot Jan 28, 2026
bcfef7b
Expand effort estimate with detailed breakdown and justifications
Copilot Jan 28, 2026
34185f8
Add JSpecify @NullMarked annotations to all remaining files
Copilot Jan 29, 2026
2a6c04a
Address code review feedback: fix comment, restore license, add nulla…
Copilot Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Expand effort estimate with detailed breakdown and justifications 
Co-authored-by: andimarek <1706744+andimarek@users.noreply.github.com>
  • Loading branch information
@andimarek
Copilot and andimarek committed Jan 28, 2026
commit bcfef7b74a4dcac410acfeb0474957fc21d6b828
48 changes: 40 additions & 8 deletions JSPECIFY_MIGRATION_PLAN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,14 +240,46 @@ When annotating the API, consider:

## Estimated Effort

- **Phase 1-2** (Core + Impl): ~8 files, 2-3 hours
- **Phase 3** (Stats): ~11 files, 1-2 hours
- **Phase 4-5** (Instrumentation + Scheduler): ~6 files, 1-2 hours
- **Phase 6-7** (Registries + Reactive): ~5 files, 1 hour
- **Phase 8** (Annotations): ~6 files, 30 minutes
- **Final verification and testing**: 1-2 hours

**Total estimated effort**: 6-10 hours
### Per-Phase Breakdown

| Phase | Files | Time Estimate | Justification |
|-------|-------|---------------|---------------|
| **Phase 1-2** (Core + Impl) | 8 files | 2-3 hours | `Try.java` and `DataLoaderOptions.java` require careful analysis of nullable generics and multiple nullable fields. Implementation classes need review of internal null handling. |
| **Phase 3** (Stats) | 11 files | 1-2 hours | Mostly straightforward classes with few nullable members. Context classes are simple records. |
| **Phase 4-5** (Instrumentation + Scheduler) | 6 files | 1-2 hours | Methods explicitly return nullable `DataLoaderInstrumentationContext`. Requires attention to null callback patterns. |
| **Phase 6-7** (Registries + Reactive) | 5 files | 1 hour | `DispatchPredicate` is simple. Reactive subscribers follow established patterns. |
| **Phase 8** (Annotations) | 6 files | 30 minutes | Annotation definitions rarely need null annotations; quick review only. |
| **Final verification** | N/A | 1-2 hours | Full build, test suite, and enable `AnnotatedPackages` option. |

### Time Estimate Rationale

Each file requires the following activities:

1. **Analysis** (~5-10 min/file): Review all fields, parameters, return types, and generic bounds
2. **Annotation** (~5-10 min/file): Add `@NullMarked` and `@Nullable` annotations
3. **Compilation check** (~2-5 min/file): Run `./gradlew compileJava` and fix NullAway errors
4. **Iteration** (variable): Complex classes may need multiple rounds of fixes

**Complexity factors that increase time:**
- Generic types with nullable bounds (e.g., `Try<V>`, `DataLoader<K, V>`)
- Classes with many optional/nullable fields (e.g., `DataLoaderOptions`)
- Interfaces that return nullable values (e.g., `DataLoaderInstrumentation`)
- Chained builders or fluent APIs

**Factors that decrease time:**
- Simple data classes with all non-null fields
- Annotation definitions (usually no changes needed)
- Classes that already follow non-null patterns

### Total Estimated Effort

| Scenario | Hours | Conditions |
|----------|-------|------------|
| **Optimistic** | 6 hours | Experienced with JSpecify, no unexpected issues |
| **Expected** | 8 hours | Normal pace, some debugging of NullAway errors |
| **Pessimistic** | 10 hours | Complex edge cases, API design decisions needed |

**Recommendation**: Plan for 8 hours, which allows for one full working day or 2-3 focused sessions.

## References

Expand Down