OpenJS Foundation OpenJS World 2021 - Development, 2 Jun 2021

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Upgrading to Fastify 3 - Austin Akers, Microsoft

Description

Upgrading to Fastify 3 - Austin Akers, Microsoft

The lessons learned upgrading our codebase from Fastify 2.x to 3.x and how to mitigate migration headaches.

Join the speaker for live Q&A on Slack, channel - #openjs_world-development
Wednesday, June 2 from 14:20 - 14:40 PDT / 23:20 - 23:40 CEST
Thursday, June 3 from 13:00 - 13:20 PDT / 22:00 - 22:20 CEST

A

Hello, everyone thank you for coming to my talk today. My name is austin akers.

A

I am a software engineer at microsoft and today we'll be discussing upgrading to fastify 3, but more so the lessons learned from doing that now, uh as a brief overview over the course of this presentation, we'll be going over how we upgraded one of our back-end services, docs render, which is a service that improves the rendering and versatility of what we're able to do for the microsoft documentation from and, as I said, we upgraded it from fastify version 2 to fastify version, 3..

A

First, we'll give a brief, backstory and disclaimer about our code base.

A

Then we'll go over the five lessons and some of these lessons might actually sound more like tips more so than they are lessons, but nonetheless, five lessons during the process of this fastify upgrade and just as a heads up these five lessons are also the heart of the presentation and last but not least, will then end with the migration summary everyone cool with that awesome, the backstory.

A

Now, let's start on the backstory and well for a quick disclaimer for anyone watching this talk, I wanted to talk about our code base before the upgrade first off before we upgraded to fastify 3, our codebase was already using typescript.

A

Certain topics or points in this talk could prove to be a bit a bit of a different experience for you, if you're not using typescript, and that's primarily because of us, taking advantage of the type system provided within typescript right and fastify itself, along with our code base, uh are both written in typescript next, our code base really isn't that large, and I say that you know relative to an enterprise code base right, especially uh especially that now I honestly would have to say that our code base would be the equivalent size of maybe a view.

A

Twos code base maybe reacts, but I just wanted to highlight that specifically because for individuals who may have a larger code base the lessons or approaches that I'll be discussing over the course of this presentation may not be applicable to your code base and, last but not least, all of our dependencies were current while upgrading. We didn't have to worry much about breaking changes uh in other libraries, which is very nice, so that made the upgrade less complex in comparison to a lot of the upgrades I've done in the past on other projects.

A

Now that we've covered all those three points, let's dive in lesson, one understand the breaking changes, just like with many other libraries and frameworks, major versioning, usually comes with well breaking changes.

A

An example would be going from view two to view three, um I was gonna, say angular, one to angular, 2 um and so on right, um but if you think uh of, if you think a major versioning upgrade of a library framework is going to break many parts of your application, one thing that you need to do is you need to document the process right document that end-to-end process of how you might want to upgrade and uh tackle that right um and within doing so too uh assess the possible pain points within your application for for documenting just about anything, I typically use onenote.

A

I know some people uh use uh notion. I've just simply been using onenote since uh college, if probably even high school right. So I'm just very familiar with that, but utilize that or those those applications to map out what parts or files of the code base that might give you trouble over the course of the upgrade.

A

I also, if you don't know already fastify has a migration guide, so I recommend, if you haven't already look into that migration guide. That is very helpful and there are very you. There are useful snippets in there. That'll show distinct examples from version festival version two to fastify version, three and lesson: two fix the foundation and go upwards or, in other words, establish a stable foundation and build on top of that.

A

When I joined the team and microsoft, I took the initiative. After talking to my boss, you know setting up my environment and doing what uh and all the onboarding stuff of saying, hey. You know what I want to try tackling this major upgrade.

A

Now I initially tried the standard approach of version bumping and digging into the large list of errors and attempting to uh tackle that turns out that wasn't the best approach. It was rough. I ended up abandoning and deleting the branch because it was so bad, which brings me to uh my point right.

A

This upgrade itself took took me several tries, so what I ended up doing was creating a fresh branch uh and attempted to find a different approach, so what it initially came up with, or what we eventually came up with- was tackling the upgrade incrementally so stripping down the app to its basics. Functionality fix that foundation and then uh tackle the upgrade and well essentially increments right, so adding on other plugins as well, and the best part about this is that fastify made that approach uh easier because of its plug-in center architecture.

A

Now, as you can see to the right, there are some plugins we've created and, um as and as you can see here, we have render we have engine off context, content, locale and error right. Well, what I ended up doing was that I narrowed down the functionality to a core plug-in within our app and went onward from there and that core plugin was render, which then speaking of plugins brings me to uh my next point.

A

Inside of this point, the plugin system, the plug-in system changes, were probably my favorite when upgrading the error messages, just in general, especially around plugins, were quite helpful after uh upgrading our functions uh after upgrading our functions became more concise and easier to read and a great example of that is, if you look here to the uh you know this: the code snippets from version two to version three, so let's go ahead and take a look at that right, as you can see here from version two we're exporting a fastified plugin uh and, as you can see here, we have three parameters inside of this uh one, stating that oh, this is a pastifi that you know the instance within this is a fastify instance.

A

You know we have plug-in options and also next callback, but if we take a look at version, three we're able to consolidate that uh you know these four lines of code into one line and that's consolidated into the fastify plug-in callback interface.

A

Now uh again, uh you know so you know this right. Here is a great example of uh having you know of our function, declarations becoming a lot more concise from version two to version three right, and on top of this, if you look at it, it's also easier to understand.

A

Now, with all of that being stated, I didn't really just come to this uh conclusion uh for the most part, from looking at the errors within the uh with you know, within the error messages in the cli right, although they were very helpful, uh there was still a level disconnect, on my end on being able to truly understand how certain things work in the upgrade, which brings me to my next lesson, which is also a great point of reference as well lesson: three referencing, the fastify test cases now, as I stated before, the error messages um contained only a certain amount of information.

A

While it was very helpful, I then tried to go out and reference the migration guide uh as great as that was as well too. It also still had limited information, and so what I ended up, having had to do what I ended up doing was going inside the fastify source code and looking at the test cases that that implement things that I felt as though I may need, or that you know, replaced a certain functions or certain interfaces within uh version two.

A

uh You know for version three and a great example of that again, if you want to take a look at this uh dive into the fastify source code inside the test, folder look for plugin, dot, test, uh hyphen d dot, you know ts and what you'll see here is uh several things we have.

A

As you can see here, you know at the bottom, you'll find a testify, plug-in async test case and you'll also find a fastify plug-in callback test case as well, and these right here these test cases provided a skeleton for the functions that I uh you know for my functions for version three. You know for our code base when we were converting it to version three which is really nice and to really put that into an example.

A

As you can see here, what we're doing is that we're going to take that that test case or like you know that snippet of code, which is the test plugin async, which is implementing a you know, as I said, just implementing the fastify plug-in async interface and we're going to go ahead and try to convert our version to a code snippet into uh our version 3.. Now the thought process that I took into uh you know converting that version to uh you know stuff.

A

Within our version, 2 codebase into version three was specifically around plugins was establishing on o. Is it a plugin right now, as you can see here to the left, we have uh site routes, which is a plugin as you'll see, and it's asynchronous right and the instance on it is happens to be an instance of fastified. You know inheritance fastify instance right. So what do we? What can we- and you know, what can we uh infer from that? Well, this right here happens to be a fastify plug-in.

A

That is a synchronous, and if we look at our version, three, let's go ahead and take that information that we learned and implement that right. So looking at that test case above as we can see here, is that what we've learned is that we now have a fastify plug-in. That is also that is asynchronous and for version three, we did exactly that right.

A

So we now converted that version to cloud into uh into version three, and we can see that we are using fastify plug-in async, so uh certain uh cert, just a certain thought process that went behind this and if you really sometimes even just talking out loud and trying to figure out figuring out a lot of this really comes to help in regards to uh you know, in regards to the upgrade as well too, but nonetheless, the test cases proved to be very helpful, and that was also a point of reference that I went to a lot over the course of the version.

A

2 diversion 3 upgrade.

A

Next lesson: 4 now I always want to say this, but typescript typescript typescript. I cannot tell you enough how having our codebase in typescript made. This upgrade substantially substantially less complex in comparison to what it probably would have been uh if we were using just vanilla, javascript and that's primarily because of the typed, the type system.

A

Now just in general, I'm sure you can probably go online and find hundreds of talks about typescript and about how amazing it is, but for me specifically, especially when it came to integrating myself uh inside the code base, but also uh you know, just in general um typescript is honestly expedited my workflow right and over the course of you know these. uh You know over the course of the upgrade as well, uh because of typescript I was able to just. I was able to better dissect a lot of the errors that I was getting right.

A

A lot of these different error messages and be able to dive in look at a lot of the different interfaces and types and being able to better understand what exactly is going on at the heart of these errors, but also within fastify as well. Considering that they converted their code base into typescript and last but not least, it also lowered the bell curve right for me to be able to dive in and to effectively contribute into the code base, because I was able to better understand what exactly was going on inside our code base.

A

So, as we have here is just a snippet of uh just a part of the uh fastify code base, you know just for loggers and interface uh logger interface, so.

A

Now, uh last but not least, we also have lesson five, which I cannot say this more than enough having uh test cases right, in fact, just having test coverage in general turned out to be exceedingly helpful over the course of the upgrade.

A

Now uh again, our uh you know, the test coverage uh inside our inside docs render happened to be around 70 to um 80. We had in regards to uh coverage right, so we had quite a quite a bit of test cases right and just overall, although the test coverage itself wasn't 100, um that's improving right.

A

Hopefully, you hope to get to 100 percent uh test coverage inside your app, but 70 to 80 percent uh was still very um helpful now and just in general right having test cases, and especially during um major upgrades like these, with breaking changes being able to have a point of reference and also being able to check uh how functionality was before, and also the and also after the upgrade, uh instilled a lot more confidence within the changes that were being made within our application right, because the last thing you want to have are uh just you know, having some sort of errors uh that are that, there's some silent errors or just errors in general that you just you know that will essentially make it just slightly that'll, essentially affect functionality or turn something to be slightly off right and last but not least, there was also a level of consistency right so um again, as I said it before there was that point of reference of functionality being able to know before and after hey.

A

This is what our application. You know how it worked before the upgrade and we're wanting that same end result uh to happen. So we aren't compromising.

A

You know compromising our end user experience, uh but having that level of consistency and being able to check that uh you know before, um and also after the upgrade proved to be a lot more uh just a lot more, it just made us feel a lot more confident in regards to uh you know the code base after the upgrade and if you haven't already, I recommend you uh well hey honestly.

A

The best time to get started is now, but if you're looking for a testing library, what we use for docs render is node tap or better yet node test. Anything protocol is what I'm remembering it as I'd have to check, take a look but we're using nodetap.

A

um So if you aren't familiar with that search it up, I recommend it. I really really like it and what we have here at the very bottom, as I said, insert this code coverage a a test case. uh Tdd, test driven development is pretty awesome, so if you aren't doing it, you should definitely do it. Okay, now, with all those five lessons covered uh the migration uh well, at the end, it was successful right, but what exactly made that migration or made our migration successful?

A

Well, first off I mean we upgraded to fast by three virtual clap. I know I love the excitement, everyone right. Second, there were no console errors and that's always a great thing.

A

Third, our code came out to beco.

A

Our code came out to be a lot cleaner and even more concise than what it was uh in version, two of what we're using for fastify right and as we saw earlier and in one of the lessons we saw how we were able to consolidate four lines of code into really one- and I said, as you saw, there was probably two and that's because of the word wrap, but it was essentially consolidating four lines of code into one line and so that conciseness made it- and uh you know and cleanliness made it- made it much much easier to read and also reference back to whenever it was necessary when going over the course of the upgrade and also another thing.

A

uh Many of our test cases didn't break now, granted some of them or quite a few of them needed to just have some minor tweaks and that's because of the upgrade itself right when you're mocking certain things. But for the most part, a lot of our test cases didn't break, which is a good thing which goes to show us that our functionality remained, uh if not similar the exact same before, but also after the upgrade, with some minor exceptions.

A

And last but not least, what, in my opinion, is a determining factor. The main determining factor on whether a migration was successful is the deployment and our deployment was.

A

Smooth now for recommendations uh again uh after listening- and you know looking at the migration summary going over our five lessons, my recommendation for anyone wanting to upgrade from version two to version three.

A

First off document those changes right document, the changes of and research, those changes that uh you know, that might prove to be very um you know, intriguing or uh that might prove to be a pain over the course of that version to the version through upgrade and also assess your code base right next work from bottom to top, so establish a firm foundation and build on top of that right now. What we had initially, as you saw was render, was our core plug-in.

A

It was the heart of the application and being able to build up from there uh made everything much much easier and, as we started building on top of render, you know we were able to have even more points of reference, but also uh having that strong foundation made the upgrade, go a lot smoother and last and then another thing as well, make sure you reference the fastify source code and also the test cases, and- and this goes for almost anyone or anything.

A

You know anyone who's wanting to find ways, or you know when doing a migration, especially a major migration, wanting to better understand the ins and outs of what exactly is going on and how my code base is affected, but also utilizing that as a point of reference for creating- or you know, essentially creating skeletons for a lot of your new functions that or that you'll be using right and another thing that again, I recommend everyone does is take advantage of typescript. If you haven't already, please please do it.

A

Typescript is phenomenal and again, if it wasn't for our codebase being in typescript. I do wholeheartedly believe that our upgrade would prove to be a bit more difficult than what it uh already you know than what it really was, or could have been right so again, typescript type subscribe, script and, last but not least, uh having great test coverage in your application.

A

Now test cases are amazing, but again we were able to have roughly around 70 to 80 percent of our app just you know, being covered in tests, so test coverages or test cases are a great way to make sure that your um that your application, uh you know, has a specific functionality so before and after the upgrade having that level of consistency, but also having that source of truth to reference to make sure that nothing breaks silently within your application is fantastic in my opinion.

A

So if you enjoyed this talk, let's connect my twitter is my twitter. Handler is what tweetmonster999, uh if you have any questions again, if you don't want to connect on twitter connect with me on linkedin or better. Yet, if you think I'm pretty cool, which you know, I think I kind of am right, feel free to follow me on github, my github name is b-boy acres. Thank you again for coming to this talk.

A

I hope you enjoyed it and I hope everyone is enjoying uh not only just this conference right, a lot of amazing speakers out here and I hope that you're able to uh well actually tweet me if you find a really awesome point or something interesting that you uh just that you found out or or something you've learned throughout the course of this. uh You know this conference so again. Thank you. I hope you all have a wonderful morning afternoon and evening since we're all around the world, and I hope to see you all again thanks.