When is responsible abandonment the right choice?

When no one is going to take it over and continuing to ship releases would be misleading. The Open Source Collective's guide lists three signs: (1) the project has been in NEEDHELP for more than 6 months with no one stepping up, (2) the problem is solved better by a successor project, or (3) the codebase is so far behind upstream changes that reviving it would be a full rewrite anyway. In any of these cases, retiring the project cleanly is more respectful of users than leaving it in a frozen-but-discoverable state.

What should I do before archiving my GitHub repo?

Six things: (1) update the README with a clear 'this project is no longer maintained' banner at the top; (2) add a deprecation/README notice explaining the timeline; (3) cut a final release with the deprecation noted in the changelog; (4) update the package registry (npm deprecated, PyPI development_status 7, RubyGems is_outdated, Packagist abandoned with a replacement); (5) post a public announcement 30-90 days before archiving, on the repo, your blog, and any community channels; (6) only then archive the repo. The GitHub blog's official guidance is to give 6+ months of notice for projects with active dependents.

How do I mark an npm package as deprecated?

Use the `npm deprecate` command: `npm deprecate "This package is no longer maintained. See for the successor."`. The deprecation message shows up in every `npm install` of the package, which is the right place to surface it. Also set the `deprecated` field in package.json. The message should include (1) when the deprecation started, (2) what users should use instead, and (3) a link to a migration guide if there is one. The npm deprecation does NOT delete the package — it just warns.

How do I deprecate a PyPI package?

PyPI doesn't have a built-in deprecation field, but you can set the development status to 7 (Inactive) in your setup.py or pyproject.toml classifiers, and you can upload a final release with a clear 'This project is no longer maintained' note in the long description. The successor-projects mechanism on PyPI (per PEP 541) also lets you request a transfer or co-maintainer if the original maintainer is unreachable. The closest thing to npm's deprecation is the Trove classifier.

Guide

How to responsibly abandon an open source project

Q: What's the difference between abandonment and a handoff?

A handoff is when a project finds a new maintainer and continues. Abandonment is when the project ends — gracefully, with proper notice to users, or ungracefully, with the project just dying. This guide is for the graceful version: when a project should end (the maintainer has moved on, the problem is solved by something else, or the project is no longer maintainable) and the responsible thing to do is give users time to migrate.

Q: Should I delete the repo or just archive it?

Archive, don't delete. Deleting the repo destroys every fork relationship, every issue history, every star count, and every existing user's reference to the code. The only situation where deletion is appropriate is when the code itself is a security risk (e.g. a vulnerable version of a library that should not be installed) or when the project was created in error. For 'I just don't want to maintain this anymore' situations, archive is the right move.

Q: Can a project come back from archive?

Yes. GitHub allows unarchiving a repo at any time (Settings → unarchive). The star count, issue history, and forks are all preserved. The pattern is: archive the project, give users 6-12 months of notice, and if no successor has emerged by then, leave it archived. If a successor does emerge later, unarchive, hand over, and the project lives again. The archive state is a pause button, not a delete button.

A 2026 guide for maintainers who want to retire a project gracefully. This is the complement to the maintainer handoff guide: a handoff finds a successor, an abandonment ends the project. Both are legitimate. Both deserve a proper plan.

Published July 13, 2026 · ~6 min read · synthesizes the GitHub blog's "Dos and don'ts when sunsetting open source projects," the Linux Foundation "Winding Down" guide, and the Open Source Collective's "Handling Burnout and Career Planning."

The short version

Decide: handoff (find a successor) vs. abandonment (end the project). They are different things.
Give 6+ months of public notice. Post on the repo, your blog, and any community channels.
Cut a final release with the deprecation noted in the changelog.
Update every package registry (npm deprecate, PyPI classifier, Packagist abandoned).
Update the README with a clear "this project is no longer maintained" banner + successor link.
Archive the repo. Do not delete. Archive is a pause button, not a delete button.

When abandonment is the right call

The Open Source Collective's burnout guide lists three signs that a project is a candidate for responsible abandonment rather than a handoff:

The project has been in NEEDHELP for 6+ months with no one stepping up. At this point, the project's likely future is silent abandonment anyway. A planned abandonment respects users more than letting them discover a dead project on their own.
The problem is solved by a successor project. If the use case is fully covered by a more actively maintained alternative, the right move is to deprecate the old project and point users at the new one — not to keep both alive.
The codebase is so far behind upstream that reviving it would be a full rewrite. This is rare but real. Sometimes the cost of catching up is higher than the cost of starting fresh. A clean deprecation with a "use X instead" is better than half-maintained dead code.

If none of these apply, you probably want a handoff instead. The 41% revival rate (per the 2019 arXiv study) is real, and most projects deserve a chance at it before going to archive.

The 6-step responsible abandonment process

1. Announce publicly, 6+ months before archive

The GitHub blog's official guidance: projects with active dependents need 6+ months of notice, ideally longer. Make the announcement on the repo (pinned issue), your personal blog, the project's mailing list or Discord, and any place where the user community gathers. Be explicit about the timeline: "I will archive this repo on 2027-01-15 if no successor has stepped up by then."

2. Update the README with a clear deprecation banner

A short, prominent banner at the top of the README. Include the date of deprecation, the successor (or "no successor — see alternatives"), and the timeline. Example:

> **This project is no longer maintained as of 2026-12-01.**
>
> The repository will be archived on 2027-06-01. No new releases will be
> published. Issues and PRs are closed.
>
> **If you're starting a new project**, use [successor-name](https://github.com/...)
> instead — it covers the same use case with active maintenance.
>
> **If you depend on this project**, see [MIGRATION.md](MIGRATION.md) for
> the migration path. You can continue to use this version indefinitely, but
> there will be no security patches after 2027-06-01.

3. Cut a final release with a clear deprecation note

Increment the major version (semver: 2.0.0 → 3.0.0) and note the deprecation in the changelog. The final release should install cleanly, pass the test suite, and have no half-finished refactors. This is the version that people will pin in their lock files for years.

4. Deprecate in every package registry

Different ecosystems have different mechanisms:

npm: npm deprecate <package> "This package is no longer maintained. See <URL> for the successor."
PyPI: Set development_status = 7 (Inactive) in your setup.py classifiers. Upload a final release with a deprecation note in the long description.
Packagist (PHP): Mark the package as abandoned and provide a "use X instead" replacement. Composer will warn on every install.
RubyGems: Push a final release with a "DEPRECATED" note in the description.
CPAN: Set the ADOPTME pseudo-user in the permissions file. This is the established CPAN signal.

5. Write a MIGRATION.md (if there's a successor)

If there is a successor project, write a migration guide. The minimum useful version: the import statements change, the API calls that changed with code examples, and a one-line "if you were doing X, do Y now." Link to the migration guide from the README banner and the deprecation message in the package registry.

6. Archive the repo. Don't delete.

On the announced date, archive the repo. The archive is a pause button: no commits, no issues, no PRs, no comments. The code stays accessible, the history stays intact, every fork relationship is preserved. Do not delete the repo unless the code itself is a security risk or was created in error. Deletion destroys the reference graph and the history, and you don't own the right to take those away from the people who depend on the project.

The succession escape hatch

The 6-month public announcement is also a succession window. If someone does step up to take over during that period, unarchive the repo, hand over, and the project lives again. The Linux Foundation's "Winding Down" guide and Jason Turner's NDC 2026 talk both emphasize this: the announcement is the deadline, not the death sentence. If you set the deadline and someone meets it, you unarchive.

For the 6-month window, drop the project on BreakPoint as well. The median time from drop to first PR on BreakPoint is 23 days. If a successor emerges there, the archive becomes a no-op.

Frequently asked questions

What's the difference between abandonment and a handoff?

A handoff finds a new maintainer and the project continues. Abandonment ends the project. This guide is for the second case. See the maintainer handoff guide for the first.

Should I delete the repo or just archive it?

Archive, never delete (unless the code is a security risk). Deletion destroys forks, history, and the reference graph. Archive is a pause button — you can always unarchive later.

How do I deprecate an npm package?

npm deprecate <package> "This package is no longer maintained. See <URL> for the successor." The message shows up on every npm install. Also set the deprecated field in package.json.

How long should the notice period be?

6+ months for projects with active dependents, per the GitHub blog's official guidance. Longer is better. The 6-month window is also a succession window — drop the project on BreakPoint and someone may take it over.

Can a project come back from archive?

Yes. GitHub allows unarchiving a repo at any time. The star count, issue history, and forks are all preserved. Archive is a pause button, not a delete button.