Modernize the old system first and build the compatibility ladder

The first time I opened a Java project from twenty years ago, the first thing I saw was not the code smell, but the age smell. The build.xml is still there, but the pom.xml is not there; the directory structure is old-fashioned, the test entrance is also old-fashioned, and even “whether it can rebuild a runnable product” needs to be reconfirmed. The most common mistake at this stage is to focus on classes and methods and ignore that what really blocks modernization is the environment and entrance.

The first thing to do when modernizing old systems is to build a compatibility ladder. The base of the ladder usually has only one thing: to make the old system run stably within the old rules, and preferably to serve as a time capsule. Docker, old JDK, old build tools, old test commands, these things look crude, but they are very effective. As long as this base is not upright, every subsequent change will mix in new noise: whether it is the code that is broken, or the JVM, image, architecture, and plug-ins that are broken, it is impossible to tell.

Then it was the turn to choose the bridge. The goal of the bridge is very specific: one end is connected to the old source code, and the other end is connected to the new machine. This project finally fell to Java 8 and Gradle 7.6, which just stuck on the constraints of both ends: Java 17 is no longer willing to compile the source code of Java 1.5, and Java 6 cannot run into the native environment of ARM64. If the bridge is wrong, modernization will be stuck in the tool chain; if the bridge is right, subsequent migrations will be able to move forward step by step.

The most useful thing here is to let the large model do the organizing and translation. It can help translate Ant logic into Gradle, map directories back to the old layout, and move out those repetitive and mechanical configurations. For example, explicitly point the source code directory to the old path, and add a custom task to run the old main() test:

java {
    sourceCompatibility = JavaVersion.VERSION_1_5
    targetCompatibility = JavaVersion.VERSION_1_5
}
sourceSets {
    main {
        java {
            srcDirs = ['java']
        }
    }
}
tasks.register('runLegacyTest', JavaExec) {
    mainClass.set(project.findProperty('mainClass'))
    classpath = sourceSets.main.runtimeClasspath
}

The significance of this configuration is to make the rules of the old world explicit. The most troublesome thing in old projects is often not the lack of ability, but that ability is hidden in habits. The test is run through the main() entry, the source code is placed in the old directory, and the build is written assuming the path in the Ant era. Copilot can save time here, but it saves translation time, not judgment time.

Judgment time cannot be outsourced. Gradle 8 looks newer, Java 17 looks more modern, and jumping directly up also looks cleaner, but these options may not satisfy the constraints of old source code and old tests at the same time. The biggest fear in modernization is to regard tool upgrades as progress and running commands as understanding the system. As long as a project has not nailed the operational baseline, green testing is not considered a victory, it can only be considered as not hitting the exposed surface for the time being.

The approach I trust more is to first break the problem into four levels: whether it can be run, whether it can be edited, whether it can be tested, and whether it can be modified. The first level is to reproduce the scene, the second level is to determine the bridge, the third level is to determine what the old test has saved, and the fourth level is the real refactoring. Copilot is particularly useful on the first two levels. It is suitable for physical work following logs and directory structures, and for piecing together fragmented clues into a readable map. On the fourth level, the model should only be responsible for transportation and prompts, and people have to rely on people to make decisions.

The most valuable result of modernizing the old system is to turn a bunch of things that “should work” into “things that actually work and we know why they work.” Once this compatibility ladder is established, the subsequent dismantling will have a rhythm and the changes will have boundaries. Copilot is like an assistant on the front line at this time, holding a flashlight to look at the age, entrance, and dependencies. What really determines the direction is the judgment of the history of the old system.