Skip to main content
Published in Engineering Insights

When the Only Developer Who Knows Your System Leaves

When the Only Developer Who Knows Your System Leaves
Table of contents
  1. What should you do first when the only developer who knows your system leaves?
  2. What is the bus factor?
    1. Is the truck factor the same thing?
    2. How do you calculate the bus factor?
  3. Who owns the code a contractor wrote?
  4. How do you take back access without breaking the system?
  5. What should you capture before the developer's last day?
  6. How do you keep the system running while nobody knows it well?
  7. What does this look like for a construction estimating tool?
  8. Should you hire a replacement, bring in another contractor or hand it to a firm?
  9. How does a new team learn a system nobody documented?
  10. How did Gnar learn Fitbit Plus, a codebase it did not write?
  11. Should you rebuild the system instead of learning it?
  12. How do you make sure one person never holds the system again?

When the only developer who understands your system leaves, do five things in order. Take control of the code and every account. Capture what the developer knows while they can still answer questions. Hold changes that can wait. Get someone new to read the code. Then decide who owns it next. This guide is for an executive in that spot. Think of the CEO of a construction firm whose estimating tool was built by one contractor. It covers who owns the code, how to take back access, what to capture before the last day, and how to stop one person from holding the system again. It is important because nobody else can safely change that tool until the knowledge is shared.

Engineers call this risk the bus factor: how many people would have to leave before nobody knows how the system works. A system one person built and runs alone has a bus factor of one. Avelino and his coauthors studied 133 popular projects on GitHub. They found that "the majority of our target systems (65%) have TF <= 2", meaning two or fewer people. TF is the truck factor, another name for the same measure (Avelino et al., 2016).

The Gnar Company reads code for this exact case. Its free audit has a path for code "someone else left behind". The codebase audits page puts it this way: "We explain what the main parts of the code do, so the next team knows what it is working with".

What should you do first when the only developer who knows your system leaves?#

As general advice, first do the steps that get harder once the developer is gone: control of the code and the accounts, then knowledge capture, then a pause on changes. Hiring and rebuild choices come after. If the developer has already left, ask whether they will answer questions for a few paid hours, and lean harder on step 4.

  1. Take control. Move the code repository, the hosting account and every password into company accounts while the developer is still on good terms.
  2. Capture what they know. Book recorded working sessions on the jobs that break most and on how a change gets deployed.
  3. Hold changes that can wait. As general advice, nobody should start new feature work on a system that nobody else can fix.
  4. Get the code reviewed. An outside reader can tell you what state the code is in and what it does.
  5. Decide the owner. A hire, another contractor or a firm, picked on what the review found.

Step 5 is also where a buyer of new software can avoid the problem next time. Gnar's application maintenance and support page covers software Gnar builds. It gives two ways out: "You can transition to your internal team with our support, or keep us on through Maintain, our optional monthly support retainer".

What is the bus factor?#

The bus factor is the number of people who would have to leave before a project stops. Google's book on software development, Software Engineering at Google, puts it bluntly: "Bus factor (noun): the number of people that need to get hit by a bus before your project is completely doomed" (chapter 2). The name comes from an accident nobody wants. The real point is any absence.

The same chapter lists the ordinary versions: "Someone might get married, move away, leave the company, or take leave to care for a sick relative". A contractor who takes a bigger client counts too.

A low bus factor means high risk. The CHAOSS project, which publishes health measures for open source software, now calls it the Contributor Absence Factor. Its page says: "A lower Contributor Absence Factor indicates higher dependency on fewer contributors, posing a risk if these individuals leave the project" (CHAOSS).

Is the truck factor the same thing?#

Yes, the two names describe the same measure. Avelino and his coauthors say the truck factor "states the minimal number of developers that have to be hit by a truck (or quit) before a project is incapacitated".

How do you calculate the bus factor?#

One research method estimates the bus factor from who wrote which files. In the Avelino method, each file gets its main authors from the commit history. Then the author of the most files is removed, one at a time, until the remaining authors cover less than half the files. The method assumes a system "will face serious delays or will be likely discontinued if its current set of authors covers less than 50% of the current set of files in the system".

As general advice, measure the bus factor for each critical part of the system as well as for the whole. Researchers from Bilkent University and JetBrains Research surveyed 269 engineers for the Bus Factor in Practice study (Jabrayilzade et al., 2022). Writing about large teams, the paper says "the bus factor problem can happen when even a single critical module reaches bus factor zero". The engineers in that study also wanted the bus factor reported with "Information on code complexity of the implicated parts".

Who owns the code a contractor wrote?#

Under federal copyright law, the author owns the work first. A contractor's code belongs to your company if it was made for hire or if the rights were moved to you in a signed writing. This is general information, not legal advice. Ask a lawyer before you rely on any contract.

Section 201(a) of the Copyright Act says: "Copyright in a work protected under this title vests initially in the author or authors of the work". Section 204(a) says "A transfer of copyright ownership, other than by operation of law, is not valid unless an instrument of conveyance, or a note or memorandum of the transfer, is in writing and signed" by the owner or the owner's agent (Title 17, chapter 2).

The Copyright Office's Circular 30 names two situations that make a work made for hire. One is work by an employee "as part of the employee's regular duties". The other is a commissioned work, which must meet four requirements, including "an express written agreement" signed by the parties and a fit with one of nine listed types, such as a compilation. The circular is firm: "If a work fails to satisfy any of these requirements, it is not a work made for hire".

As general advice, pull the contract this week. If it has no signed assignment of the code, ask the developer to sign one while you are still on good terms.

How do you take back access without breaking the system?#

Move every account into the company's name before you revoke anything the developer uses. As general advice, replace each key the system runs on with a new key the company holds, confirm the system works on the new key, and only then revoke the old one. Do it one key at a time.

Each item below cites its source:

  • Revoke credentials and keep access. NIST's control catalog, SP 800-53, says to "Terminate or revoke any authenticators and credentials associated with the individual" when someone leaves. It also says to "Retain access to organizational information and systems formerly controlled by terminated individual" (NIST SP 800-53 Rev. 5, PS-4).
  • Find the secrets in the code. The OWASP Secrets Management Cheat Sheet warns that many organizations keep secrets "hardcoded within the source code in plaintext". It adds: "When secrets are no longer required or potentially compromised, you must securely revoke them to restrict access" (OWASP).
  • Move the repository, then check what came with it. GitHub's docs say "If the transferred repository contains webhooks, services, secrets, or deploy keys, they will remain associated after the transfer is complete" (GitHub Docs). Review those keys after the move.

What should you capture before the developer's last day?#

Capture the knowledge that is not in the code: why choices were made, how a change gets deployed, and what breaks most often. Store it in company accounts. Recordings kept in the developer's own accounts leave with them.

Martin Robillard of McGill University interviewed 27 developers and managers about knowledge loss after people leave (Robillard, 2021). One executive asked a departing developer "to identify pull requests that contain all the [relevant code]", and "those pull requests became kind of a reference implementation". A developer described the opposite. After the person left, "they cleaned up everything, including the recordings. So the recordings were lost".

A capture list built on those lines and three more primary sources:

  1. Walkthroughs of real changes. Have the developer narrate past changes that touched the main parts, as in Robillard's example. Save the recordings in a company drive.
  2. Why the big choices were made. Michael Nygard wrote that "One of the hardest things to track during the life of a project is the motivation behind certain decisions" (Nygard, 2011). His fix is the architecture decision record, "a short text file".
  3. Steps for the failures that keep coming back. Google's SRE book says "clear and thorough troubleshooting steps and tips are valuable when responding to a high-stakes or time-sensitive page" (Google SRE book).
  4. Code comments where the logic is odd. Software Engineering at Google says "implementation comments transmit knowledge across time" (chapter 3). It warns that comments "need to be actively maintained or they can quickly become out of date".

How do you keep the system running while nobody knows it well?#

Prove the backups restore and add tests that record what the system does today, while changes wait. Those steps give a new team a way to check its first small changes.

Test the backups. NIST's CP-9(1) control says to test backups "to verify media reliability and information integrity". As general advice, restore a copy into a test setup now, while the developer can explain any surprise.

Pin down how it behaves today. Michael Feathers calls these characterization tests. "The purpose of characterization testing is to document your system's actual behavior, not check for the behavior you wish your system had" (Feathers). He adds that "you often discover behavior you weren't aware of". As general advice, these tests act as a safety net while the new team learns the system.

What does this look like for a construction estimating tool?#

For a construction firm with two weeks' notice, those weeks go to moving accounts and recording sessions, then changes wait while an outside team reads the code. In this illustrative example, the firm's estimating tool was built by one contractor, and nobody else has ever deployed it.

In week one, the firm moves the repository into a company GitHub account, moves the hosting account into the company's name and copies every password into the company vault. The contractor records three sessions: how a new material price gets in, how a change goes live, and what to do when the nightly price import fails. In week two, the contractor writes notes on why the pricing rules work as they do, and the firm restores a backup into a test copy while the contractor can still explain any surprise. After the last day, the firm replaces each of the contractor's keys with a company key, confirms the tool still runs, revokes the old keys one at a time and asks an outside team to read the code.

Should you hire a replacement, bring in another contractor or hand it to a firm?#

As general advice, pick the option that fits the size of the system and who will run it next. A hire suits a system the business will grow for years. Another contractor suits a small, stable tool. A firm suits a system that needs more than one person on it. The table below is general advice too.

Option When it fits What to check first
Hire a developer The system is core and will keep changing for years Whether you can find one: one engineer in the Bus Factor in Practice study spent 3 years looking
Another contractor The tool is small, stable and changes rarely That one contractor still means a bus factor of one, so plan the next handover now
A software firm The system needs several skills or more than one person on call That the firm reads the code before it quotes, and that the code stays in your accounts
Keep the old developer on call They left on good terms and will answer questions A few paid hours a month while the new owner learns

Robillard's interviews fit the last row in part. He found that "the departure of a knowledge owner does not necessarily imply a complete disengagement from the project".

A firm is not always needed. In Gnar's words: "If your own team has the capacity and the direction, you do not need us".

How does a new team learn a system nobody documented?#

A new team learns an undocumented system by reading the code, testing what it does and asking the people who use it. As general advice, write down what each step finds.

Robillard's interviews found a cost when people rebuild lost knowledge on their own: "the high level of effort required for this activity can interfere with work". The paper also notes that "Recreating the knowledge can be a social activity, which may need to include some of the non-developer stakeholders". For an estimating tool, those people are the estimators who know what a correct bid looks like. Software Engineering at Google adds a habit for the new team: "The first time you learn something is the best time to see ways that the existing documentation and training materials can be improved".

Gnar's audit is built for the reading step. The codebase audits page lists "What the code really does" in the result: "Where nobody wrote down how it works, we explain what the main parts do". Its FAQ adds: "In a Gnar code audit, senior engineers read the code. They work out the main business rules nobody wrote down, like how an order gets priced".

How did Gnar learn Fitbit Plus, a codebase it did not write?#

Gnar learned Fitbit Plus by auditing its code and solving problems next to Fitbit's own engineers. The software came to Fitbit with an acquisition, and Fitbit's team was busy building the replacement.

The Fitbit case study says "Fitbit's internal team didn't have the bandwidth for this task". The learning step sits in one sentence: "We performed detailed code audits and collaborated with the internal team to solve problems as they arose, and we became proficient on the existing system codebase". The case study reports that Fitbit was able to "successfully transition hundreds of thousands of existing Fitbit Plus clients to the new platform while continuing to meet and maintain all client commitments and service‑level agreements".

Should you rebuild the system instead of learning it?#

As general advice, decide on a rebuild only after someone has read the code. The read shows what the system does, which rules matter and what a fix would involve. Without it, a rebuild has to find again the rules nobody wrote down.

Gnar's audit ends in that decision. Its page lists "Keep it, fix it, or rebuild it" with "Your options, and the next steps for each one". Gnar's guide to replatforming, refactoring and rebuilding gives the order: "Before you choose, get the code audited and ask how the old system keeps running while each new part takes over".

How do you make sure one person never holds the system again?#

Give every critical part a second person who can change it and keep the notes with the code. Those two steps raise the bus factor above one, and keeping every account in the company's name keeps control of the system.

Each item below cites its source:

  • A primary and a secondary owner. Software Engineering at Google says good documentation plus "a primary and a secondary owner for each area of responsibility" raises a project's bus factor.
  • Review requests. GitHub lets a repository name code owners in a CODEOWNERS file. "Code owners are automatically requested for review when someone opens a pull request that modifies code that they own" (GitHub Docs).
  • Knowledge sharing and rotation. In the Bus Factor in Practice study, engineers suggested "writing documentation, organizing talks by key developers, doing code reviews". They also suggested "rotating people between the project parts".
  • Tests that teach. Michael Feathers writes: "When we write characterization tests we build up our knowledge of what the code actually does". When Avelino and his coauthors asked developers which practices soften the loss of a top author, the paper reports: "Documentation is the practice with the largest number of mentions across answers (36 answers), followed by the existence of an active community (15 answers), automatic tests (10 answers), and code legibility (10 answers)".
  • Training through teaching. Google's knowledge sharing chapter says its engineers "teach others in a variety of ways, such as office hours, giving tech talks, teaching classes, writing documentation, and reviewing code".

For the next system you buy, put the handover in the contract. Gnar's post on who maintains custom software after launch says "The handover should give you everything a new team needs to run, change and deploy the software without calling the old one".

If the code is in front of you and nobody can explain it, start with a review. Ask for the code audit. No fee, and it can come back saying your codebase is in reasonable shape.

Frequently asked questions

What is the bus factor?

The bus factor is the number of people who would have to leave before a project is in serious trouble. Google's book Software Engineering at Google defines it as the number of people that need to get hit by a bus before your project is completely doomed. Researchers call the same idea the truck factor. A system only one person understands has a bus factor of one.

How do you calculate the bus factor?

Researchers estimate it from the commit history. In the method from Avelino and his coauthors, each file gets its main authors. Then the top author is removed again and again until the rest cover less than 50% of the files. The number of authors removed is the estimate. For a system one contractor wrote alone, the answer is one.

Who owns the code a contractor wrote?

Under federal law, copyright starts with the author. A contractor's code is a work made for hire only in the cases the Copyright Office lists. A transfer of copyright ownership, other than by operation of law, is not valid unless it is in writing and signed. Find the contract, look for a signed assignment, and ask a lawyer before you rely on it.

What should a developer hand over before they leave?

The code in a repository your company owns, every password and key, the steps to deploy a change, and recorded walkthroughs of the jobs that break most. As general advice, also ask for short written notes on why the main design choices were made. Keep those notes in the repository with the code.

Should we rebuild the system after the developer leaves?

As general advice, not before someone reads the code. A rebuild started in a hurry has to find again the rules the old system already follows. Keep the system running and get an outside read of its state. Then decide whether to keep it, fix it or rebuild it.

Can The Gnar Company review code that another firm built?

Yes. The Gnar Company audits code that another vendor built. It reads that code before agreeing to take any of it on. The AARP Foundation work started that way. Gnar checked tools a previous firm had built and took them over. Ask for the code audit. No fee, and it can come back saying your codebase is in reasonable shape.

How do you increase a low bus factor?

Put a second person on the system's work and write down what only one person knows. Engineers in the Bus Factor in Practice study suggested writing documentation, talks by key developers, code reviews, rotating people between parts of the project and hiring new people to increase the knowledge redundancy.

Stay In The Loop

Never miss an update. Get the latest blogs, webinars, and expert insights straight to your inbox from The Gnar.