7 Practical Tips to Handover a Repo

Handing over a repository can be daunting. Make onboarding and offboarding easy for developers with these 7 practical tips.

7 Practical Tips to Handover a Repo


Take a deep breath

Pick one successor (or more)

Isolate outgoing dev (from the code)

Assign critical issues to incoming dev

Clean up for outgoing dev

What to document

Bonus documentation

Break ups are always hard but they happen. Whatever the reason, you need to act quickly. The following days are critical to keep your business running as smoothly as possible.

Offboarding is like onboarding but more compressed and more intense. 

The situation calls for efficiency. You have 2 weeks (4 if you’re lucky) to transition.


Take a deep breath

First of all, take a deep breath. You need to accept that your plans will change and your roadmap will be delayed. 

  • Your metrics (cycle time, MTTR, and others) will be severely impacted.
  • Your incoming dev may take 1-3 months to get comfortable with his new repo.
  • It will take resources to hire, replace and retrain (3-6 months).

Your main focus however is MTTR on the repo of the outgoing dev. The worst situation is having your app offline while your incoming dev struggles to figure out stuff. 

There is going to be frustration and stress because of the time pressure of offboarding. If you were lucky to have a high bus factor, then transition should be easier.


 - Dilbert by Scott Adams

Credit: “Dilbert Comic Strip on 2006-12-08 | Dilbert by Scott Adams”


Pick one successor (or more)

For obvious reasons, you’ll want a successor who has close skills with your outgoing dev. You’ll also want someone who is willing to support even though the project may not be “sexy”. You may need to motivate by putting the team first.

If you have the luxury of choice, optimize for speed of learning. Pick someone who is:

  • Familiar with the code
  • Familiar with the technology or framework
  • Can learn quickly and pragmatically

Consider augmenting your incoming dev with someone on another team who can carry the Maybe in DevOps or QA?

A little help can go a long way to take the pressure off and avoid a single point of failure.


Isolate outgoing dev (from the code)

It’s very tempting to have the outgoing dev to fix bugs or to make a final release. It’s faster and it’s easier. Don’t do it. Resist the temptation. Even if it’s critical.

You need to simulate life without the outgoing dev on day 1. Because very soon, that will be the hard reality.

⬜ Announce to stakeholders who the incoming dev is

⬜ Route all stakeholders request to incoming dev 

⬜ Update repos access (e.g. BitBucket, Github)

⬜ Update issue tracking system (e.g. JIRA, GitHub issues

⬜Update chat rooms (e.g. Slack, Microsoft Teams)

⬜ Update mailing lists (e.g. Google groups, support email)

The incoming dev should be the only person allowed to talk (about the code) to the outgoing dev.


Assign critical issues to incoming dev

 - Dilbert by Scott Adams

Credit: “Dilbert Comic Strip on 2006-12-08 | Dilbert by Scott Adams”


⬜ Build and run the project

⬜ Run automated tests (or run manual tests)

⬜ Fix a simple bug

⬜ Re-deploy the existing project with a fix 

⬜ Fix a critical bug

The incoming dev should be in the pilot seat. His hands should be on the keyboard and mouse as the outgoing dev only watches.


Clean up for outgoing dev

The goal of the outgoing dev is to make it as easy as possible for the incoming dev to take over.

The outgoing dev should take a seat back as much as possible.

⬜ Document (see below for a checklist)

⬜ Clean up code 

⬜ Remove unused code

⬜ Minor refactoring that can help understand the code

⬜ Review Pull/Merge Requests from incoming dev

⬜ Pair programming with incoming dev (if possible)

⬜ Clean up ticketing system

⬜ Remove obsolete issues

⬜ Remove obsolete new features and improvements

The incoming dev should review documentation for accuracy. Does it match what he has seen in the code?


What to document



⬜What does this code do? (Screenshot or high level description)

⬜What are the frameworks and technologies used?

⬜Build and run

⬜ How to build, run and deploy

⬜ How to run automated tests (write description of BDD tests as an alternative)

⬜ How to configure the application

⬜ Repo organization

⬜ Where are the runtime entry points to the code? 

⬜ Where are the key folders?

⬜ Where are the key files?

⬜ How to monitor the app

⬜ Where are the logs? 

⬜ How do you know the app is failing or offline?

⬜ How do you know the app is slow?

⬜ How to troubleshoot?

⬜ How to recover from failure? (reset, restart)

⬜ A list of inbound dependencies (e.g. front end, mobile)

⬜ What are the expectations? Are there any contracts?

⬜ Who is the owner for that dependency?

⬜ A list of outbound dependencies (e.g. database, cloud storage)

⬜ How to access those dependencies (with credentials, passwords or keys)

⬜ How to monitor those dependencies 

⬜ How to deploy, backup and reboot those dependencies 

⬜ How to recover from failure? (reset, restart)

⬜ A list of local dependencies

⬜ How do you handle issues with storage space?

⬜ Are there any scheduled jobs which rely on this repo?

⬜ Issue tracking

⬜ Where is the issue tracker?

⬜ List of open bugs

⬜ List of closed bugs that have occurred in the last 6-12 months from your issue tracking system



High level diagrams are less practical but useful to offer a larger context.

⬜Architecture diagram

⬜Sequence diagram

⬜Entity Relationship diagram

⬜Data flow diagram

⬜What are the business concepts?

⬜What are the technical concepts and components?


Bonus documentation

The list of tasks above can be overwhelming. There is a lot to cover for the basic handover. If you are fortunate to have high bus factor, time and resources, consider some nice to have:

⬜ What are customer expectations of uptime? Is there an SLO or SLA?

⬜ What are the coding standards ?

⬜ What’s the Git branching model?

⬜ What are the plans for the product for the long term?

⬜ What are the plans for the technology for the long term?

⬜ What technical debts need to be addressed in the long term?

⬜ What licensing do 3rd party libraries use?

⬜ How secure is the app? Are there audits we need to be aware of?

Featured posts