.jpg)
.png?width=1600&name=Repurpose_%20How%20a%20Vaadin%20Migration%20Assessment%20works_%20A%20Case%20Study%20(1).png)
In this article, we look at an actual Migration Assessment case that Vaadin expert Jean-Christophe Gueriaud and I recently completed for a customer in Germany. I review the different steps and offer behind-the-scenes insight into how these projects work. The case covers a typical 2-week assessment for a migration from Vaadin 7 to Vaadin 14.
THE WEEK BEFORE
Practical preparations
About a week before the assessment project starts, I get in touch with the customer to set up protocols. The aim is to make sure they know what we need (project sources, POMs and JARs, VPNs and links to their Nexus, if they have one), to find out how they prefer to securely send us their code, and to determine what kind of chat collaboration software our two teams will use. We always offer our own infrastructure—our dedicated SFTP and a Slack channel—but we respect that each customer may have their own preferences, policies or ports they have blocked in their firewall.
I also send them a copy of the interview questions. One of the first orders of business when the assessment starts is to interview the key stakeholders. Preparing the answers always takes time, so we make sure they get the questions a few days in advance.
THE DAY BEFORE
Smoke-test the inventory
The day before the assessment starts, I do a test of the source inventory and a “sanity” check to make sure what we have is complete. I unpack the sources and pull basic “number of files” and “number of lines of code” counts that we can use to verify the inventory, without the risk of opening up too many technical details before the project even starts. The file transfer checks out successfully, as it typically does.
THE FIRST DAY
Interview and tool setup
When the project starts in earnest, the expert and I tackle the customer interview as soon as possible. During the interview, we let the customer zoom in on the application itself and the reasons they have already considered about why they want to migrate, and what outcomes and processes they are looking for. We get a sense of where the customer stands on a number of key parameters, like going for a phased or a big bang approach, what their time constraints are, which parts of the application they want to preserve and which they are looking to aggressively modernize at the same time as the migration.
We also establish any specific free-form questions the customer wants the assessment to explore. During this interview, the customer is curious about how they can pave the way for future development work on the migrated application so as to support both server and client-driven development models concurrently. Can the traditional Java UI developers and a newer team that focuses on JavaScript both do their different thing at the same time, after they migrate to Vaadin 14? How can the customer make this work in a safe way that doesn’t result in the application becoming a mess? Since the client- driven model is so new in the Vaadin framework, best practices about the interoperability of the two models are still in flux. Jean-Christophe and I will have to think about the question and see what insights we can get from our product developers.
With the interview done, the expert and I dive straight into the application project and get it cleaned and installed, using Maven to resolve all dependencies as is typical. Once our project is built, the first information we use our tools to extract is the physical/logical mappings for all instances where the code touches a binary. This will show us version conflicts, any spurious dependencies we can ignore, and the big picture on which JARs are used heavily.
In this case, we find three JARs that seem like they were made by the customer, but we don’t have the sources that correspond to them. Will these JARs be impacted by the migration? A question the customer will have to help answer...
THE FIRST WEEK
Dependency discovery
We let the customer’s core question about concurrent programming models simmer as we take stock of the application in its current state. Using more of our tools, we look at the dependencies in the code from a library, component and API perspective. The customer’s code is over 600 kLOC, so we spend a lot of time looking at analyzed pivot reports and from these reports we dig down into the code.
The expert and I both document our findings (backed up by data) so we can easily see which components are used most frequently and will benefit from careful, up-front planning. Components that are used less frequently may be more appropriate to resolve on a case-by-case basis. This is the bulk of the discovery work and it takes us several days to complete.
THE SECOND WEEK
Migration impact
At the start of the second week, we examine bigger technical facets in the application. These cross-cutting concerns span multiple classes, and are related to topics like drag-and-drop, theming, navigation, and localization. As the week progresses, we start to shift our attention from a technically-detailed level to understanding how the migration impacts the application dependencies. We also take the wider organizations that need to run the application into account, and consider what tools are available to reduce costs and risks.
Early in the second week we give a first presentation to the customer in which we explain the main findings from the technical discovery. A number of challenges start to become clear. First, the Vaadin 7 Table component has been used a lot in the customer’s application. In Vaadin 8, this component was replaced by the Grid component, which has a very different API, and continues to be used in Vaadin 14. Second, we see the customer has developed large SCSS files, which will have to be retargeted for the newer Custom Elements specification.
With the first presentation done, we shift to detailed listings of the component dependencies and their closest mappings to the target Vaadin 14. This list is the foundation for our effort estimations. From this list, we also group together components that are treated similarly, like VerticalLayout and HorizontalLayout.
We also find time to turn our attention to the customer’s question about migrating the application to support both client-driven and server-driven development models. We organize meetings with our colleagues in the Vaadin framework development team to get the most recent feedback. Our colleagues pass on two lessons to us. First, the key to maintainability is to have clarity of ownership by the client or server of the component state at any one time. Second, the granularity at which to determine ownership is the component level. Ownership then bubbles up through the visual object tree from client to server as you approach the root. We tie this information together into a practical recommendation and include that in the assessment document.
THE LAST DAY
Everything in alignment
For the past two weeks, Jean-Christophe and I have collected and studied many facts about the case. It is now time to put them all together: everything we know about the customer’s current application, the mappings identified by the customer and us, our estimates, and the final situation the customer originally said they wanted to achieve. The question becomes: does it all match?
It’s at this point that the expert and I get the most technically creative and come up with our considerations for shortening time to market, reducing risk, or decreasing cost. This often means we look at the business angle of the migration and identify what the core options are.
In this case, our customer’s vision of supporting both client-driven and server-driven development teams concurrently means they will have to write a lot of code to put the required application infrastructure in place. Doing all of this work upfront, before implementing the views as the customer originally planned, will cause a bottleneck in getting the migrated system into production.
To relieve the pressure on timelines, the expert and I compile a list of some of the largest legacy components the customer has. We prepare to show that wrapping techniques can be used for the most complex ones. By doing some targeted bottom-up wrapping, the customer can shave months off their critical path to deploying the first version of their migrated application, without compromising the quality of the final product.
We review the unit and UI tests of the current application and see how these could be reused to test the migrated version.
THE FINAL MEETING
Proposing solutions
The final meeting is the most business-oriented one, at which we discuss estimates and their aggregation, the magnitude and complexity of the transformation work that will be needed for binding, presentation, and view logic, and the work breakdown structures for the whole project.
We deliver our assessment report, which contains insight for all stakeholders, including developers keen on finding the right new APIs, line managers estimating what skills they will need to finish the migration and for how long, and directors interested in how the migration brings the company closer to their strategic technical vision, what other options may be available, and how the costs and benefits of these options compare.
We present the key considerations for accelerating time to market and lowering risks. We also present opportunities to better future proof the application by investing more upfront, for example by creating strategic abstractions of the new Vaadin APIs, creating an application pattern guide with naming conventions, and transforming the current ad-hoc CSS rules into a formal design system.
And finally, we come to the part about presenting and exploring opportunities. As in most organizations, application migration is a completely separate activity from regular maintenance and users expect or require new features on an ongoing basis. Migration typically requires resources that are normally dedicated to implementing these features and users may grumble about delayed timelines. We highlight parts of the migration that can be performed without domain knowledge of the business, and can therefore be outsourced to other developers.