The sword is yours: transferring projects to another team unscathed

First up, let’s share a few words about the project we’ll discuss in this article, eBaymag. It is an official eBay B2B tool that helps sellers implement cross-border trades. Vendors can use it to share their listings on markets in a diverse range of locations—these include France, the United States, Canada, Australia, Great Britain, and Spain—with 120 territories available for sellers in total.

We already described our entire experience in this article: eBaymag magic: under the hood of the international eBay spinoff.

Well, to be more precise, we described everything except this handover process.

Why not just up and leave a project?

So, if you’ve never experienced this kind of project transfer before, let’s examine what is possibly the worst-case scenario. In such a situation, to put it bluntly, the consulting team (for whatever reason) just, kind of… leaves. We consider this option to be completely unacceptable. You may have come across contractors who’ve made a dissatisfying, unceremonious exit in the past. But, for us, the handover process is a built-in part of our workflow.

As a team of consultants, we know it’s natural for successful startups to build their own internal teams, so from the very start of our engagement, we’re already planning for that. We help our clients transfer knowledge, train our successors, and then the customer can continue without us; perhaps consulting us from time to time as needed.

But this isn’t just about making a good impression on a client. Transferring a live project with a large, active user base is an area where a handover error can directly impact the client’s business.

In the case of eBaymag, we managed to avoid serious problems although we had a relatively large code base, a technically sophisticated project, and a large number of edge cases:

• Relatively large codebase: Since the project was already “live” with a large number of active users and with planned features and improvements yet to come, the new team had to pick up the ball as quickly as possible so that users would not be affected by the switch going on behind the scenes.

• Technically sophisticated project: In addition to its internal complexity, the project was heavily dependent on external systems from both eBay and delivery services. There was no guarantee that things could get out of hand even with the automation of routine tasks, monitoring, and alerts. The team would need to be able to respond to these events immediately and correctly. For example, importing a large number of products (there were many large sellers who managed hundreds of thousands of items/goods) could require manual queue balancing. Ignoring such load spikes could cause performance degradation and, as a result, a drop in the quality of service for other users.

• A large number of edge cases: These were related to certain components of eBay: listings, policies, shipping, and so on. For instance, eBaymag’s team tried to make the listing process as easy as possible for the user by converting user-created business policies in eBay (i.e., payment, shipping, and return policies) into a format suitable for target sites. In most cases, this process worked perfectly. Still, sometimes it required additional adjustments: a return policy, for example, could require warehouse data clarification or changes in the list of countries where a return was unavailable. We handled such cases in close cooperation with the support team, and the new team had to know all the nuances and details.

Do any of these seem familiar to you? If not, that’s OK. After all, each project has its own distinctive considerations that would be evident to those involved. For us, the issues above were the most pressing, and after 7 years of hard work, we had fallen in love with this project, so it was important for us to get it right.

The handover plan

In our case, we had to take into account the following factors:

• The transfer time was limited to approximately one month (due to reasons beyond our control).
• We didn’t know how much time we would actually need: the amount of knowledge to transfer and the amount of time the other team had for training was unclear.

It is important to understand that the project handover can not be endless.

It was necessary to draw up a plan to infuse the maximum amount of knowledge and practice in the given time.

Let’s go through each stage of that plan.

Transfer preparation

This phase included several critical steps.

1. Updating documentation in a knowledge base. For this project, we used Notion. The documentation contains most of the knowledge about the project: the app’s functionality, experiment results, release plans, a list of services, a description of processes, and so on.
2. Handing over accounts and access rights. In some cases, it was enough to change an email in a service, while others required us to look for workarounds. For example, in the case of Jira, we had to export all tasks and import them into a new Jira account.
3. Preparing a plan for the code base and infrastructure handover.
4. Task scheduling for smoother project onboarding. Many tasks covered separate, large code areas, so we had to assign them to different team members.

Codebase transfer

After laying that groundwork, we came to the most “sensitive” stage of the project handover, transferring the codebase:

Introducing the code and project structure

On the first call with the new eBaymag team, we took the engineers through all the main parts of the project.

W e gave a top-level explanation of the features and guided the team through the upcoming work scope.

Demo

At this point, we presented a demonstration of separate domains (components) of the project. Ready-made docs from previous onboardings and presentations came in handy here.

Introducing a new team to the project

It was necessary to assign tasks to the new team immediately. This involved the distribution of the first tasks, well suited to help the team start learning the code. And we also began to draw up future tasks based on existing plans (technical debt, planned improvements, and optimizations) and ideas, as well as based on an understanding of the new team’s skills.

To illustrate how this process broke down in practice, let’s consider an important task related to translations and specific selections.

We then divided that task into the following subtasks:

• Problems with translation variants of certain specifics, e.g., color/colour.
• Import errors due to the lack of specifics.
• Problems with brand name translations, music album titles, etc.—in short, things that didn’t actually require any translation.

Thus, we identified the main domains (components) of our application and assigned tasks for these domains to different members of the host team while educating their specialists.

Sometimes, this approach can cause a bus factor, but this can be offset by calls and discussions.

Notably, the calls we held were not 1-on-1, and we did our best to have at least several members of the new team at them). Eventually, this flow significantly speeds up the handover process.

Routines onboarding

At the next stage, we organized everyday routines. For example, in our product development process, we had a dedicated person on “pager duty” every week. This person is first in line to react to any monitoring shenanigans and who would sort out all the recently filed product bugs. We needed to hand this (and other routines) over to the new team. Here are some management ideas:

Gradually transitioning routines

We organized routines so that the new team’s responsibility would gradually increase. During the first stage, the “host” team wasn’t complete, and their team leader worked with us for the first shifts.

Others joined later, but the team leader already had enough project-specific information to mentor them by that time.

Thus, these duties became the full responsibility of the host team. Of course, we were ready to help if necessary, but it was critical for the new team to handle everything independently.

They succeeded. 💪

Emerging problems analysis

Problems analysis was, of course, also collaborative. Our collaboration at this stage extended to debugging, too—a perfect way to share substantive, practical, and useful information.

Pull request code reviews

GitHub Pull Request code reviews were especially beneficial in cases where changes were made to critical or complex code areas.

Transferring the infrastructure

In all our projects, we’re already preparing for the infrastructure handover phase during the planning stage.

We understand that a project will inevitably be transferred to the client’s own environment.

We formulated several rules to achieve this aspect of the handover:

• Our configuration doesn’t use any unique in-house developments; it’s built on the basis of available products.
• Infrastructure must have consistently stable performance; it could be handed off “as is” at any moment, and we’ll be sure that it will continue to work and survive the additional load. A new team should be able to work with it at any time.
• The client should be able to make any changes they need (or completely switch to their own workflow.) That’s why we try to avoid vendor lock-in and adhere to the “Infrastructure as Code” principle. This is also for the sake of saving the changes history. It helps a project live on (stay afloat), even if a client doesn’t have a DevOps/SRE team with deep enough qualifications to fully support it at the moment of handover.

The standard infrastructure handover process looks like this:

Prepare and create all accounts in advance

For this project, we needed to transfer access to the Google Cloud accounts and to change the owner of the GitHub repositories. The process was carried out in several stages since the host team initially wanted to study the entire infrastructure.

Consultation on the entire infrastructure

You need to understand that:

• Any automation is always sophisticated.
• The new team’s approach to infrastructure may differ from yours.
• Due to its history, compromise solutions may remain in the project.

Therefore, holistic consultation is critical. At such consultations, we demonstrate our infrastructure to a client step by step, from beginning to end.

The review began with the Terraform/Terragrunt configuration, which manages infrastructure objects at the level of public clouds. Next, we introduce our typical Kubernetes cluster maintenance and management, including Argo CD configuration, our Helm chart set, and monitoring configuration. Then, we show which components of the project are running, where they are, and how they are deployed. We often review all the namespaces one by one with the team, so as not to miss any detail.

This is a long process, but it is very important. It can be divided into several parts so that the other team can revise and carefully re-read the source code of the configuration that we have just talked about.

If a team doesn’t have enough experience with some of the tools we use, or when engineers have different levels of knowledge, we hold online or offline master classes—and we’ve been doing that for close to ten years. Further, we shape the agenda specifically for the needs and topics of a particular project.

Migrate all integrations and repositories correctly

The next important step is to move all repositories with code and the Terraform and Kubernetes configuration to another organization on GitHub owned and managed by the new team. Evil Martians always split their “infrastructure” repository into two: one with a base configuration and one with a private configuration for each project. (This way, we can always keep the basic configuration up-to-date and guarantee planned regular updates). When we hand over a project, we make a copy of the latest revision, paste it to the client’s GitHub organization, and switch Argo CD to work with it.

In addition to Argo CD and repositories, it was important to immediately transfer CI/CD (in this case, CircleCI) under the control of a new team. This allows the new team to jump in when they need it and, which is most critical, gives the client the opportunity to better assess potential financial/time costs and work scope.

This particular project was accepted by the client as is, along with all the current staging. They had to do most of the adaptation on their own: reconfiguring monitoring and deployment in a way that was convenient for them. But, thanks to the streamlined infrastructure handover process, everything went as smoothly as possible. Moreover, the team was able to independently solve problems that would later appear.

Transferring pitfalls

Of course, if you’re dealing with such a large and complex project, you may face some emergency situations. Let’s be transparent about some of those:

Breaking changes in API during transfer

The policy functionality required urgent changes. Most of those were implemented, but using them in production could cause some problems that would require a thorough deep dive. As a result, the new team had to learn the policy nuances. However, at the initial stage, the host team only had surface-level knowledge about policies, which was understandable. We couldn’t leave them to gradually learn the policies (because problems could occur at any time)—and instead provided a crash course to everyone at once.

Bus factor for individual project components

In particular, with this project, a bus factor could happen in such areas as product names/descriptions translations or compilation/comparison of specifics (on different sites). Mistranslations and incorrect compilation could (and did) lead to massive errors in the product locations (like an album from The Doors being listed in the “Furniture” department). eBaymag, as a project with a rich history, had some legacy code in its codebase, and translations were an example of this. At the time of the transfer, the host project team didn’t have a sufficient depth of knowledge on translations to solve these issues immediately. Here, collaborative debugging sessions were helpful as well to get everyone up to speed.

Situations requiring a quick response

Unfortunately, no project is safe from those times when something urgent crops up. When faced with such cases, we went ahead and solved problems in the usual way, but at the same time, we tried to make the most of them. So, instead of acting just on our own, we called them to the attention of the new developers. This way, they at least could understand what was happening. At a result, the new team received valuable practical knowledge and, after a while, they were able to respond on their own as needed. In the same way, together with the new team, we sorted out problems from the support team.

General hints for a successful project transfer!

To sum things up, here’s a pool of our general recommendations:

• Be prepared that your project could be transferred to another team at any time.
• This was our legacy, now it’s yours! Make an attempt to get to and learn pieces of the codebase you never touched before, and describe the largest and/or most critical problems long before the handover starts. Try to minimally burden the host team with legacy code, and remember that new people mean new approaches and fresh eyes. If you correctly identify any problems, the new team can solve issues that you never got around to.
• The new team could come from any background, so be ready for that; the knowledge and training process can take an unpredictable amount of time. Being prepared can help mitigate this.
• Work closely with the team leaders from the host team to achieve synergy. Help them with task planning and delegation. They know their own strengths much better than you do; you know the product better.
• And, of course, encourage initiative: the more interesting the project is for the new team, the less work you’ll have, and, most importantly, the more prosperous the project’s future will be.
• Conduct the most strict reviews possible. Please remember: shortcomings currently in the code can lead to problems in the future. And it’s the host team will have to live with the project.

In general, we recommend preparing for any handover in accordance with the principle set out by Yamamoto Tsunetomo, Buddhist priest and samurai, in his book Hagakure:

If by setting one’s heart right every morning and evening, one is able to live as though his body were already dead, he gains freedom in the Way. His whole life will be without blame, and he will succeed in his calling.

---

And one more thing: if you’ve got a problem or project in need, get in touch with Evil Martians!. We’re always primed and ready to take up the sword and get you where you need to be! ⚔️