How to safely move off your homegrown feature flag management system.
This article provides a roadmap for how to effectively migrate to LaunchDarkly's feature management platform. This is the third article in our three-part series on building vs. buying a feature flag management system. Part one focused on what is needed to build your own solution. Part two presented questions you should ask to determine if you've outgrown your existing solution. Part three provides guidance and tips on conducting a migration from a homegrown or open-source solution (OSS) to LaunchDarkly.
Challenges of migrating
Moving from one technology to another isn't always a smooth process. I recently upgraded my cell phone. The migration and upgrade was a frustrating process. First, I got frustrated with my current phone; once that frustration reached a tipping point, I got frustrated with the phone choices, then the upgrade process, and so on. Migrating from one feature flag solution to another can be filled with similar frustrations, but it doesn't have to be if you follow the tips below.
Some potential challenges you will need to prepare for when migrating from a homegrown solution to LaunchDarkly include:
- Addressing technical debt
- Prioritizing migrations across teams
- Training team members
Engineers who learn the benefits of feature flags will eagerly create them but be far less eager to clean them up afterward. As a result, you may have hundreds, even thousands, of flags by the time you migrate. Migrating these would be an overwhelming task. What's the best way to address this technical debt? Even better, how can you avoid accumulating more in the future?
You may have deployed multiple solutions to address your feature flagging needs. Whether this was due to different teams building their own solution, or needing different OSS for multiple languages—you need to think about how to migrate all of these.
Teams and departments need training on how to use LaunchDarkly. New accounts need to be created, new processes set up, etc.
You're going to have challenges when you migrate, but overcoming those challenges will be worth it in the long run. We've grouped these tips into three categories based on when they'll come into play: Planning, Migrating, and Fixing.
11 tips to help you migrate
I'm sure you're itching to start your migration and dive into things. Before you do, take five minutes to read the rest of this article for more tips. It's better to get all the information ahead of time and set yourself up for success from the start, instead of trying to fix things later. Jumping in too soon is one stop on the way to accumulating technical debt.
Divide your migration into three phases: planning, executing, and post-migration. During the planning phase, you determine what is needed and how the migration will occur. The execution phase consists of putting the plan in place. And the post-migration phase covers how to go forward with day-to-day use.
Tips for planning
1. Plan a gradual migration
There's no need to rush with the migration or the audit. Often customers will run their old and new systems in parallel. If you have a feature currently in the middle of a rollout, or you're running an experiment, leave those running on the existing platform. Set up new flags in LaunchDarkly. It's ok to run systems in parallel for a couple of months while things wind down and your teams are trained. If you do it the right way, you may be able to avoid giant cut-over steps and downtime.
2. Keep manageable timelines
Treat the migration as a continual learning process. As the migration progresses, you'll learn more about how long each step takes. You'll also find that some steps vary wildly from team to team and are much harder to estimate. Revisit and adjust your estimates regularly to keep stakeholders informed. Be prepared to change the placement of teams and projects in the schedule.
3. Choose the right team for the pilot
If your engineering organization contains many teams, start with a single team rather than trying to migrate all teams and their projects at once. You can focus your attention on helping one team rather than spreading it across many. This project to migrate a single team, known as a pilot, is aimed at producing useful techniques and tools that other teams can use.
Pick a team that won't be under pressure during the pilot. If the team is about to start a new project in which it can use LaunchDarkly, or if there's a maintenance period coming up between projects, both of those are suitable situations for a pilot. The team should be ready to provide regular feedback on its migration process, as well as assisting in the creation of lightweight migration tools and documentation to be used by the rest of the organization.
Tips for migrating
4. Standardize a naming convention
If you didn't already have a naming convention or style guide in place for feature flags, take this opportunity to create one. As feature flag use grows in your organization, having a naming convention to identify which team owns a flag, what release it is associated with, and the purpose of a flag is useful.
Things to consider when creating a naming convention:
- Be descriptive. Verbose flag names are better than brief flag names.
- Use prefixes with a project name, team name, release, or other identifying elements.
- Specify whether the flag is temporary or permanent.
- Include a creation date for the flag to help with flag cleanup.
Change is hard. Following these tips and using LaunchDarkly's customer success team will help you get the most out of your migration.
5. Keep most of the legacy flags in the legacy system
As I mentioned above, technical debt is one of the biggest challenges of migrating. How do you migrate potentially thousands of flags safely? You don't. Take this opportunity to start over. When I upgraded my phone, I didn't automatically reinstall all the apps. I only installed the frequently-used, work-related, and important apps. The rest I ignored. When it's time to migrate feature flags, we recommend using a similar process.
How do you migrate potentially thousands of flags safely? You don't.
Look at your flags. Identify the permanent and operational flags. Which of those are still used, still needed? Configure those in LaunchDarkly. You don't need to—nor should you—migrate all your flags to LaunchDarkly.
6. Add new flags to LaunchDarkly only
You want the number of flags in the legacy system to only go down. If the team has to create new flags while migrating, those flags should only be created in LaunchDarkly.
You might wonder: if the team's existing code is only looking in the legacy flag system, how's it going to see the new flags? That's covered by our next tip...
7. Change the wrapper, not the calls
The legacy flag system probably provides an API module. It contains flag evaluation functions that are called throughout the team's application code. Instead of changing all the application code that uses flags, leave it as it is. It's much easier to change the implementation of those functions to use both the legacy system and LaunchDarkly.
We use the term wrapper to describe the changed functions because they wrap an existing API specification around a more complex implementation. Internally, the new implementation evaluates flags by querying both the old and new flag systems, and uses whichever flag it finds first. The order of querying is set by a dedicated “flag evaluation mode” flag, kept in LaunchDarkly.
When the new wrapper is deployed, it should look to the legacy flag system first. Once the team is comfortable with LaunchDarkly, and the most important flags have been migrated, you can switch the flag evaluation mode to query LaunchDarkly first.
8. Divide into projects
Projects, which are the primary organizational containers for flags, should be created at the start. We recommend creating a separate Project for each app or executable owned by a team. Learn more about Projects in the LaunchDarkly documentation.
Tips for post-migration
9. Define your process
There is no magical way to prevent technical debt from accumulating, but there are some things you can do to minimize it. First, define what done means when it comes to a feature. When you create a flag, what processes do you have in place for ensuring the flag is removed? Is a feature done when it rolls out to 100% of users, or is it done when the flag is removed from the code?
Coding a flag is a two-part process: creating a flag and removing a flag. These should not be considered two separate processes. We recommend submitting a pull request to remove the flag at the same time you submit the PR to add it.
If you don't follow this process, LaunchDarkly provides code references to help you identify where in the codebase the feature flag is referenced for easier removal.
Looking for more information on how to reduce technical debt? Check out these blog posts.
10. Use tags
If you only have a handful of flags, it's not time-consuming to find a flag in LaunchDarkly. As your number of flags grows and more teams use feature flags, this becomes harder. Tags help you organize and sort flags into groups.
For example, if you have flags related to experiments you can create an ‘experiments' tag. If you have flags for specific departments, you can create a tag with the department name. These tags can help you control which team members can read, write, or modify a flag.
Before migrating, brainstorm a list of relevant tags. You can always add more tags later, but try to limit the number of tags to make things easier to find.
11. Ask for help
When migrating, you shouldn't go it alone. Thankfully, you don't have to! LaunchDarkly's customer success engineers are here to help you get up and running. We also have self-learning options through our step-by-step guides. There's no need to reinvent the wheel; learn from others and make modifications to suit your individual needs.
Conclusion
A successful migration consists of planning, and then executing on the plan. Diving into the doing without a solid plan in place can result in the accumulation of technical debt, or problems with the migration. Take your time to review these steps, work with your customer success engineers, and you will be on your way to a successful migration.
* * *
If you're interested in further exploring whether to adopt LaunchDarkly, request a personalized demo of LaunchDarkly's feature management platform, or start a free trial.
* * *
This article was co-written by LaunchDarkly Developer Advocates Yoz Grahame and Dawn Parzych.
