Succession Planning

The bus factor is the number of people who could be hit by a bus before a project cannot continue. For most open source projects, that number is one. One person holds the credentials, understands the architecture, reviews the PRs, and makes the decisions. When that person disappears, whether from burnout, a new job, health issues, or simply losing interest, the project enters a crisis. Succession planning is the practice of ensuring that no single person's departure can kill a project.

The Bus Factor Problem

The bus factor is not hypothetical. Open source history is full of projects that were crippled or abandoned when a key maintainer left.

What a bus factor of one means:

  One person has:
    - Admin access to the GitHub repo
    - Credentials for the package registry (npm, PyPI, crates.io)
    - Access to the domain name and DNS
    - Knowledge of the build and release process
    - Understanding of the core architecture
    - Relationships with the community
    - Authority to make decisions

  If that person disappears:
    - Nobody can merge PRs
    - Nobody can publish releases
    - Nobody can fix critical security vulnerabilities
    - Nobody can update the website
    - The project slowly dies as issues pile up unanswered

Real Examples of Abandoned Projects Causing Damage

left-pad (2016):
  An 11-line npm package that left-padded strings. Used as a
  transitive dependency by thousands of packages, including
  Babel and React. The sole maintainer, Azer Koculu, unpublished
  all his packages from npm after a dispute with Kik (the
  messaging app) over a package name. The unpublishing broke
  builds across the entire JavaScript ecosystem for hours.

  Lesson: critical infrastructure should not depend on a single
  maintainer with sole control over publication.

event-stream (2018):
  A popular npm package maintained by Dominic Tarr. He had lost
  interest and handed maintainership to a stranger who requested
  it. That stranger added malicious code that targeted the Copay
  Bitcoin wallet, attempting to steal cryptocurrency. The attack
  affected millions of downloads before it was discovered.

  Lesson: transferring maintainership without vetting the new
  maintainer can be catastrophic. Succession planning is not
  just about finding someone; it is about finding the right someone.

OpenSSL / Heartbleed (2014):
  OpenSSL was used by two-thirds of all web servers but was
  maintained by a handful of people with minimal funding. The
  Heartbleed vulnerability (CVE-2014-0160) exposed the
  catastrophic consequences of critical infrastructure being
  undermaintained. While not strictly a succession issue, it
  demonstrated what happens when critical projects lack adequate
  maintainer resources.

  Lesson: critical projects need sustainable maintainer teams,
  not heroic individuals.

core-js (ongoing):
  Used by 90% of websites through transitive dependencies.
  Effectively maintained by one person, Denis Pushkarev. He has
  repeatedly asked for financial support and co-maintainers,
  with limited response. If he stops maintaining core-js, the
  JavaScript ecosystem faces a significant problem.

  Lesson: the open source ecosystem routinely depends on
  unsustainable single-maintainer projects.

Multiple Maintainers From Day One

The simplest defense against the bus factor is having more than one maintainer from the start. This does not mean equal ownership from day one. It means intentionally preparing others to take over if needed.

Building a multi-maintainer project:

  Stage 1: Contributor access
    Identify 1-2 regular contributors.
    Give them triage access: label issues, close duplicates.
    This costs you nothing and gives them ownership.

  Stage 2: Review access
    Once they demonstrate good judgment, let them approve PRs.
    You still merge, but they do the review work.

  Stage 3: Write access
    Let them merge PRs in their area of expertise.
    "You own the CLI module. You decide what gets merged there."

  Stage 4: Full maintainer
    Admin access to the repo. Publish access to the package registry.
    They can make releases independently.
    At this point, you have a bus factor of at least two.

Good maintainer candidates submit multiple high-quality PRs over months (not a burst), review other people's PRs thoughtfully, answer questions in discussions, understand the project's design philosophy, and show up consistently. Be wary of people who only contribute features they personally need, ignore code review feedback, or show interest only after being offered access.

Document Everything

Documentation is the most underrated component of succession planning. If only you know how to do a release, nobody else can do a release. If the architecture exists only in your head, nobody can maintain the code.

What to document for succession:

  Release process:
    Step-by-step instructions for making a release.
    Which commands to run, which services to log into,
    which secrets are needed, where they are stored.

  Architecture:
    How the code is organized. What the key abstractions are.
    Why major decisions were made (decision records).

  Access and credentials:
    Who has access to what. Where credentials are stored.
    How to get access to the package registry, domain registrar,
    CI/CD system, and hosting.

  Governance:
    How decisions are made. Who has authority over what.
    How new maintainers are added.

  Community:
    Where the community communicates. Who the key community
    members are. What the norms and expectations are.

  Financial:
    If the project receives donations or sponsorships, document
    how funds are managed and who has access to accounts.

The Succession Document

Create an explicit succession plan and store it where other maintainers can access it.

Succession plan template:

  # Succession Plan

  ## Current Maintainers
  - @alice — project lead, full admin access
  - @bob — co-maintainer, can merge and release

  ## Access Inventory
  - GitHub org admin: @alice
  - npm publish access: @alice, @bob
  - Domain registrar: @alice (credentials in 1Password vault)
  - Cloudflare: @alice (credentials in 1Password vault)
  - CI/CD secrets: managed via GitHub Actions secrets

  ## If a Maintainer Becomes Unavailable
  - The remaining maintainer(s) continue operations.
  - If @alice is unavailable, @bob can handle releases.
  - If both are unavailable for 90+ days, @carol (listed as
    an emergency contact) has instructions to request admin
    access from GitHub support.

  ## Adding New Maintainers
  - Minimum 6 months of regular contribution
  - Approved by existing maintainers
  - Granted triage access first, then review, then write

  ## Transferring the Project
  - If no maintainers are available, the project should be
    transferred to [foundation/organization] or archived.
  - Do NOT transfer to unknown individuals without vetting.

Transferring Ownership

When you can no longer maintain a project, transferring ownership to someone who can is better than letting it rot. But the event-stream incident shows that careless transfers are dangerous.

How to transfer ownership safely:

  1. Look within the existing community first
     Regular contributors who have demonstrated good judgment
     and sustained interest are the best candidates. They already
     understand the codebase and the community.

  2. Vet the candidate
     Check their contribution history across projects.
     Look at how they interact with others.
     Have a conversation about their plans for the project.

  3. Transfer gradually
     Give them maintainer access while you are still around.
     Let them make a few releases under your supervision.
     Observe how they handle difficult situations.

  4. Announce the transition publicly
     Tell the community what is happening and why.
     Introduce the new maintainer(s).
     Be available for questions during the transition period.

  5. Transfer all access
     Repository admin, package registry, domain, CI/CD, and
     any other infrastructure. Do not leave yourself as a
     bottleneck.

When no suitable successor exists, you have several options: add a "looking for maintainer" notice to the README, donate the project to a foundation like Apache or the Linux Foundation, archive the project, or mark it as unmaintained with a link to alternatives. Sometimes the right person is already a user and just needs the invitation.

Archiving vs Abandoning

There is a difference between archiving a project and abandoning it. Archiving is intentional. Abandoning is neglect.

Archiving:
  - Add "ARCHIVED" to the README with an explanation
  - Set the GitHub repo to archived (read-only)
  - Point users to alternatives
  - Publish a final release that is clearly marked as the last
  - The project remains available for reference and forking
  - Users know the situation and can make informed decisions

Abandoning:
  - Maintainer stops responding to issues and PRs
  - No announcement, no explanation
  - Dependencies become outdated, security vulnerabilities pile up
  - Users do not know if the project is dead or just slow
  - Other projects that depend on it are stuck

How to Archive Well

Archiving checklist:

  1. Write a final README update
     Explain that the project is archived and why.
     List alternatives if they exist.

  2. Close open issues with an explanation
     "This project is being archived. This issue will not be
     addressed. For alternatives, see [link]."

  3. Publish a final release
     Make sure the latest stable version is published and
     clearly labeled. Users locked to specific versions
     should continue to work.

  4. Set the repo to archived on GitHub
     This makes the repo read-only and displays a banner.

  5. Update package registry metadata
     npm has a `deprecated` flag: npm deprecate package "message"
     PyPI allows yanking versions with a message.
     crates.io allows yanking with a redirect to alternatives.

  6. Transfer or point the domain
     If the project has a website, either transfer it to a
     successor project or put up a notice.

For projects backed by companies or foundations, succession planning should be organizational policy: shared credential vaults, documented runbooks, regular rotation of who does releases and triage, explicit succession policies, and budget for knowledge transfer during maintainer transitions. The CNCF requires graduated projects to have a minimum of two maintainers from different organizations specifically to prevent single-company or single-person dependencies.

Common Pitfalls

• "I'll find a successor when I need one." By the time you need a successor, you may not have the energy or ability to find one. Start identifying and mentoring potential maintainers while you are still active.

• Transferring to the first person who asks. The event-stream incident happened because a burned-out maintainer handed access to a stranger who volunteered. Vet candidates thoroughly. Check their history across multiple projects.

• Keeping all credentials in one person's account. If the sole admin's GitHub account is compromised, suspended, or abandoned, the project loses access to everything. Use shared infrastructure with multiple admins.

• No documentation of the release process. If releasing requires a series of undocumented steps that only one person knows, nobody else can release. Write it down and have someone else do a release using only the documentation.

• Archiving without notice. Silently archiving a project that others depend on causes confusion and frustration. Announce the archive, explain why, and point to alternatives.

• Confusing "looking for maintainer" with "waiting for a hero." Adding a "looking for maintainer" label and then waiting passively rarely works. Actively reach out to potential successors, post in relevant communities, and make the opportunity visible.

Key Takeaways

• The bus factor is real. left-pad, event-stream, and core-js demonstrate what happens when critical projects depend on a single maintainer.
• Have multiple maintainers from day one. Even if one person founded the project, start bringing others into maintainer roles early.
• Document everything: the release process, architecture, access credentials, governance, and the succession plan itself. If it exists only in your head, it is not succession planning.
• Transfer ownership carefully. Vet candidates by checking their contribution history, communication style, and sustained interest. Never hand access to strangers.
• Archiving is better than abandoning. An honest "this project is archived, here are alternatives" is far more helpful than a slow, silent death.
• For critical infrastructure, organizational policies like shared access, documented runbooks, and rotation of responsibilities are essential safeguards against key-person risk.