Proposal: Migrate the JDK 21 annotations typetools/jdk to JDK 25

[Gaoyan1999]

This issue proposes migrating the existing annotated JDK 21 repository (in typetools) to the OpenJDK 25 release.

According to the New Contributor Projects - Case Study: JDK 25 documentation, merging existing JDK 21 annotations into JDK 25 is the principal first step for this project. I have reviewed the checker-framework and typetools repositories and have not found any active work or open PRs regarding this specific migration.

I am highly interested in leading this migration. I have already initialized the merge process locally and have successfully resolved approximately 40% of the conflicts.

I opened this ticket because the following reasons:

1. Verify that this migration is currently necessary and valuable for the Checker Framework.

2. Ensure that no other contributors are currently working on this task to avoid duplicated effort.

3. If the above are confirmed, I would like to share my detailed merge strategy and feasibility analysis (based on the project README) for review and feedback.

[mernst]

Thank you for your interest.

1. Yes, this is a very important task.
2. I am not aware of anyone else working on this task.
3. There is an outline of the work needed at https://github.com/typetools/jdk/blob/master/README.md#upgrading-to-a-new-version-of-java, but it may be missing some details, so please ask if you have any questions.

[Gaoyan1999]

Thank you for the reply.

I will share my full migration plan below. It is quite detailed (and perhaps a bit verbose), as I wanted to be thorough and avoid any missteps given the scale of this migration.

Thank you for your patience in advance.

---

JDK 25 Migration Strategy & Feasibility Analysis

Target Version: use jdk-25+36 - which is GA version. The last commit is: 6c48f4ed707bf0b15f9b6098de30db8aae6fa40f

1. Pre-merge Analysis: Identifying the Divergence Point

I performed a manual verification of the commit history to understand the divergence between the Mainline and the Target jdk-25+36(GA) Tag, and to confirm the correct repository baseline.

A. Divergence Analysis (Master Branch vs. GA Tag)

git clone https://github.com/openjdk/jdk.git
cd jdk
git log --graph | tail -r > git-log-master.txt


git checkout jdk-25+36
git log --graph | tail -r > git-log-jdk25.txt

# Inspecting the divergence
diff git-log-master.txt git-log-jdk25.txt | head -n 20

The logs confirm that the common ancestor is commit c59e44a7aa2aeff0823830b698d524523b996650 (Authored Thu Jun 5 2025).
This commit represents the historical divergence point where the release branch split from the mainline. I think this isn’t directly related to the migration, but I’m noting it here for reference.

B. Repository Verification (Mainline vs. Updates)

Crucially, I compared the openjdk/jdk (Mainline) and openjdk/jdk25u (Updates) repositories at the GA Tag (jdk-25+36). The Mainline and Updates repositories are bit-for-bit identical at the GA point.

The target commit (jdk-25+36) is 6c48f4ed707bf0b15f9b6098de30db8aae6fa40f. Note that this commit is distinct from and newer than the common ancestor found in step "A" (c59e44...).*

Since the Mainline and Updates repositories are identical at the GA point, I will proceed with the migration using the jdk-25+36 tag from the standard openjdk/jdk repository as the definitive baseline.

2. Workspace Setup

I initialized the workspace directly on the target JDK 25 GA Tag (jdk-25+36) to ensure the codebase includes all the latest features, rather than resetting to the older common ancestor.

mkdir jdk25-clean && cd jdk25-clean
git clone https://github.com/openjdk/jdk.git

# Reset to the Target Version (JDK 25 GA)
git reset --hard jdk-25+36
git branch -m jdk25-dev-merge

3. Merge

I merged the current typetools/master (annotations based on JDK 21) into the JDK 25 GA baseline. I am currently using IntelliJ IDEA for conflict resolution. I am also aware of the README-merging.el script mentioned in the documentation and plan to explore it for automating bulk patterns.

# Add typetools remote
git remote add typetools https://github.com/typetools/jdk.git
git fetch typetools

# Merge annotations
git merge typetools/master

4. Conflict Analysis & Feasibility

Based on the merge result, I have quantified the migration workload.

Category	Count
Total Annotated Files	2,081
Total Conflicts	339
Critical Conflicts (java.base)	241

A preliminary merge simulation confirms high viability with an ~85% auto-merge rate (1,742/2,081 files). The workload is concentrated on 339 conflicts, specifically 241 in java.base. I‘ve already solve 40% of them.

5. Next Steps

• Resolve all conflicts in locally.
• Update .azure/azure-pipelines.yml.m4 to reference JDK25 and readme
• Configure the repo to point to my fork (origin) and typetools/jdk (upstream).
• Open a Pull Request to track the migration progress. (strictly adhering to "Do Not Squash" policy).

git remote set-url origin git@github.com:gaoyan1999/jdk.git
git remote add upstream https://github.com/typetools/jdk.git

git push -u origin jdk25-dev-merge

• While I acknowledge that the jdk25u repository is active with post-GA patches(e.g., tagging jdk-25.0.3+1), my primary focus for this phase is to establish a stable baseline on JDK 25 GA (jdk-25+36). Once the initial annotations are merged and verified against the GA release, I plan to align the repository with the jdk25u maintenance stream. However, strictly speaking, syncing with post-GA updates is considered a future maintenance task and is outside the scope of this initial migration proposal.

[Gaoyan1999]

How to validation

When merging annotations from JDK 21 to JDK 25, I realized we need some validation to make sure we didn’t introduce any errors during the process.

I though we need two kinds of verlidations.

1. Ensure the merged JDK 25 is identical to the original (after removing annotations)

After merging, we get an annotated JDK 25. If we remove all Checker Framework–related annotations, each Java file should be bit-for-bit identical to the original one, including whitespace. I wrote a Python script (inspired by readme-diffing.el) that removes the annotations using regex and then compares the result with the original file. It’s a bit rough and may produce some false positives, so I still check the results manually, but overall it works pretty well.

2. Ensure no annotations are missing

We also need to make sure we didn’t accidentally miss any annotations. My idea is to find the files that exist in both JDK 21 and JDK 25, then count the number of Checker Framework annotations in each file. If the counts differ, we can record those files and manually check whether the difference is expected. I haven’t implemented this part yet, but that’s what I’m planning to do, if it's valuable.

[Gaoyan1999]

Hi, @mernst. I’ve finished the migration (https://github.com/Gaoyan1999/jdk/tree/jdk25-dev-merge
) and opened a PR to merge it into master, but I know that’s not the correct target branch.

I think we may need to first create a dedicated branch for JDK 25 in typetools, something like jdk25-dev, and then merge my PR into that branch. After that, all future annotations for JDK 25 could be done on this branch.

Looking forward to your thoughts.

[Gaoyan1999]

Update on 12/Feb:
I forked jdk25u to my local repo, and reset HEAD to 6c48f4ed707bf0b15f9b6098de30db8aae6fa40f, which is the last commit of the GA version. In that way, the code in jdk(https://github.com/Gaoyan1999/jdk/tree/jdk25-dev-merge) and jdk25u(https://github.com/Gaoyan1999/jdk25u) is aligned at the same baseline.

Update on 15/Feb:
Then I merged the changes from myrepo/jdk:jdk25-dev-merge into myrepo/jdk25u:jdk25-dev-merge. As expected, there were no conflicts. We can review the diff in this PR:

https://github.com/Gaoyan1999/jdk25u/pull/1/changes